# Overview

> What is the SparkU public API and why scripts output data to the Island.

## What it is

The SparkU public API is a way to display on the Island (notch/Dynamic Island) data that your own script or program collects: build progress, server metrics, a timer, a task queue. The script doesn't draw the interface — it only sends values to ready-made slots that you configure in advance.

Typical scenarios:

- **CI/deploy** — pipeline stage, branch, build link, "Open logs" button.
- **Builds** — percentage, stage, time remaining.
- **Server monitoring** — CPU, memory, latency, status "working / slow / down".
- **Timers** — countdown to end of meeting, kettle, backup.
- **AI agents ask humans** — agent sends a question with answer options and waits for you to tap on the Island.

## Model: You describe the form, scripts fill it in

```
 Settings → Custom Integrations             script / program
 ┌───────────────────────────────┐           │ sparku push deploy progress=0.7
 │ "Deploy"  address: deploy     │           │ curl --unix-socket … /v1/…
 │ fields:  title, progress, stage           ▼
 │ indicator, line, card          │      ~/.sparku/run/api.sock
 │ buttons, priority, ttl         │           ▼
 └──────────────┬────────────────┘     field values
                └──────────────────►  Island elements
```

**Integration** — name, address (slug), fields, and how they look on the Island — is created only by you: by hand in the editor, by wizard, or by importing a `.sparku` file with explicit consent. The script gets an address and token and from that point can only **write values** to fields that already exist. It cannot add a new element, button, or card — the Island layout is fixed, only the content changes.

> [!WARNING]
> Custom Integrations is an experimental feature. It may behave unexpectedly
> (cards and the Island sometimes display differently than intended), and frequent updates
> from scripts increase CPU and battery usage. The feature is disabled by default —
> you must consciously enable it in Settings after reading the warning.

## Local only, no network

The API works through a UNIX socket at `~/.sparku/run/api.sock` and exists only while the feature is enabled in Settings. There is no network port: any program **on this same Mac** running under your user can write to the integration — that is, the same level of access as any of your scripts already have. The token is for addressing, protection from typos and other scripts, not as an access boundary between processes owned by one user.

## Next steps

- [Quick start](/docs/api/quickstart.md) — enable the feature, install the CLI, send your first value.
- [Concepts](/docs/api/concepts.md) — integration, slug, token, fields, Island elements and cards, priority, value TTL.
- [Field types](/docs/api/fields.md) — what and how to send in `push`, error texts.
- [sparku CLI](/docs/api/cli.md) — all commands, flags, exit codes.