# API guide

Public capability imports, ownership, errors, and resource lifetimes.

Source: https://legend.so/spark/reference/

Import APIs and types from `@legendapp/spark/<feature>`. Use these public paths rather than internal packages.

## [Capability entry points](https://legend.so/spark/reference/#capability-entry-points)

| Public path | Responsibility | Guide |
| --- | --- | --- |
| `/app` | App context, events, activation, quit guards | [Documents and lifecycle](https://legend.so/spark/documents/) |
| `/app/documents` | File/URL requests, recent history, document controllers and reload watches | [Documents](https://legend.so/spark/documents/) |
| `/windows`, `/windows/macos` | Windows, displays, cursor, geometry, React roots, native macOS chrome | [Windows](https://legend.so/spark/windows/) |
| `/menus`, `/context-menu`, `/tray` | Owned app menus, native popups and tray items | [Menus](https://legend.so/spark/menus/) |
| `/shortcuts`, `/global-shortcuts`, `/shortcuts/commands`, `/shortcuts/keyboard` | Accelerators, command routing, persisted bindings and low-level keyboard events | [Keyboard shortcuts](https://legend.so/spark/keyboard-shortcuts/) |
| `/dialogs` | Open/save panels, message dialogs and confirmation | [Files and dialogs](https://legend.so/spark/files/) |
| `/files` | Paths, directories, byte/stream/positional IO, watches, scanning, Trash | [Files](https://legend.so/spark/files/) |
| `/settings`, `/settings/observable`, `/secure-storage` | JSON settings, Legend State persistence and selected SecureStore methods | [Settings](https://legend.so/spark/settings/) |
| `/settings/window` | Normal/virtualized settings-window composition and options | [Native UI](https://legend.so/spark/ui/) |
| `/clipboard`, `/links` | Clipboard formats and external URLs/paths | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/drag-drop` | Native drag sources and drop destinations with generic payloads | [Drag and drop](https://legend.so/spark/drag-drop/) |
| `/notifications`, `/system` | Permissions/local notifications, Dock/taskbar, login startup and power | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/processes` | Child processes and app-supplied helper executables | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/sqlite`, `/webview` | Spark-owned database and embedded browser contracts | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/audio`, `/auth-session` | Async players/media sessions and prepared browser-auth sessions | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/camera` | VisionCamera components, hooks, outputs and sessions; Nitro Image integration | [Camera](https://legend.so/spark/camera/) |
| `/updates` | Native whole-app update status, initiation, preferences and events | [Packaging and updates](https://legend.so/spark/distribution/) |
| `/ui`, `/ui/uniwind`, `/ui/classnames` | Common native controls and optional styling integrations | [Native UI](https://legend.so/spark/ui/) |
| `/markdown`, `/html` | Read-only rich text, controlled inputs, and editable previews | [Rich text](https://legend.so/spark/rich-text/) |
| `/ui/search`, `/ui/sidebar`, `/ui/split-view`, `/ui/swipe`, `/ui/glass`, `/ui/symbol` | Specialized macOS views | [Native UI](https://legend.so/spark/ui/) |
| `/ai`, `/ai/codex` | Installed AI CLI execution and optional macOS Codex supervisor | [AI execution](https://legend.so/spark/ai/) |
| `/customize` | Optional macOS app customization: generate, review, preview, and apply edits | [Customization guide](https://github.com/LegendApp/legend-spark/blob/main/docs/customize-apps.md) |
| `/contracts`, `/diagnostics` | Shared error/availability/resource types and explicit diagnostic utilities | [Shared contracts](https://legend.so/spark/reference/#shared-contracts) |

Support varies by platform. Check feature-specific availability, permissions, and [platform limits](https://legend.so/spark/limitations/).

## [Shared contracts](https://legend.so/spark/reference/#shared-contracts)

Spark-owned commands generally resolve `void`; data has explicit result types. Expected cancellation, veto, and nonzero process exit are results. Operational failures reject with `SparkError`; branch on `code` rather than parsing messages. `cause` retains underlying failures. Availability is advisory and separate from permissions.

Unknown option keys reject with `E_UNSUPPORTED_OPTION`, including unknown keys whose value is `undefined`. Promise operations reject validation failures; synchronous utilities throw. Omission leaves update fields unchanged; `null` only clears declared nullable fields. Check each operation's merge/replace rules.

Subscriptions expose synchronous `remove()`. Async registrations resolve to a handle with asynchronous `remove()`. Resource-specific cleanup uses `close()`, `remove()`, `terminate()`, or `dismiss()` according to its meaning. Stop observing when the owner ends, await required cleanup, and retain failed handles for supported retry. Concurrent cleanup joins rather than starting duplicate removals. Hooks handle late setup completions and expose cleanup-error callbacks where applicable.

Time is explicit: `timeoutMs`/Unix timestamps use milliseconds; audio positions and notification delays use seconds. File/process bytes are `Uint8Array`. Native paths, URLs, and base64 are distinct data forms.

## [Ecosystem boundaries](https://legend.so/spark/reference/#ecosystem-boundaries)

Spark owns the supported SQLite, WebView, audio, UI, and desktop contracts. Their backend objects stay private. Selected Clipboard, Linking, and SecureStore methods follow Expo semantics; that does not promise complete Expo-package compatibility.

Legend State observables, React Native, Runtimes, Uniwind, and other ecosystem libraries retain their own APIs. Use upstream imports for capabilities beyond Spark's subset and define resource ownership when mixing integrations.

## [Tooling and metadata exports](https://legend.so/spark/reference/#tooling-and-metadata-exports)

These are not application runtime capabilities:

| Paths | Use |
| --- | --- |
| `/config`, `/schema.json`, `/config-plugin`, `/expo-config` | Typed configuration, schema and Expo composition |
| `/metro`, `/native` | Metro and native discovery |
| `/runtime-entry`, `/metro-gate`, `/init-template` | Generated-project runtime/bootstrap integration |
| `/cli` | CLI executable entry |
| `/package.json` | Package metadata |

For changes to older imports and contracts, see [migration](https://legend.so/spark/migration/).

Contributors should follow the repository's [API design rules](https://github.com/LegendApp/legend-spark/blob/main/docs/api-design.md) when adding APIs or replacing backends.

[View Markdown](https://legend.so/spark/reference.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+API+guide&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Freference%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)