# SparkU API — custom integrations

> SparkU puts scripts and programs on the MacBook notch: a script pushes values over a local UNIX socket (HTTP/1.1 or the `sparku` CLI), SparkU draws them as an indicator, a status line or a card, relays button presses back and can ask the user a question.

The API is local-only: it listens on `~/.sparku/run/api.sock` while the user has turned the feature on in SparkU settings. There is no network endpoint and no cloud.
Every page below is plain Markdown. For everything in one file use `/llms-full.txt`.

## Docs

- [Overview](/docs/api/overview.md): What is the SparkU public API and why scripts output data to the Island.
- [Quick start](/docs/api/quickstart.md): Enable the feature, install sparku, and send your first value to the Island.
- [Concepts](/docs/api/concepts.md): Integration, slug, token, fields, Island, card, priority, and value TTL.
- [Field types](/docs/api/fields.md): How fields are coerced from CLI strings and JSON, push examples, and 422 error texts.
- [sparku CLI](/docs/api/cli.md): All sparku commands, their flags, token search order, and exit codes.
- [HTTP API](/docs/api/http.md): Transport, authorization, and complete list of /v1 routes — request, body, response, error codes.
- [Buttons and Events](/docs/api/events.md): Event stream /events, at-most-once delivery, sparku listen in NDJSON and with --exec, other button actions.
- [Questions to User](/docs/api/dialogs.md): POST …/dialogs and sparku ask — options, confirmation, timeout, attachment; how an agent asks for permission.
- [.sparku Files and Import](/docs/api/packages.md): .sparku format, what it doesn't include, POST /v1/imports and sparku import, user consent, risks.
- [Recipes](/docs/api/recipes.md): Ready-made examples — deploy progress, Xcode build, server monitoring, timer, task queue, agent confirmation.
- [If It Doesn't Work](/docs/api/troubleshooting.md): sparku doctor, typical errors — from missing socket to 409, request log and "Test" console.

## Документация на русском

- [Обзор](/docs/api/ru/overview.md): Что такое открытый API SparkU и для чего скрипты выводят данные на островок.
- [Быстрый старт](/docs/api/ru/quickstart.md): Включить функцию, поставить sparku и отправить первое значение на островок.
- [Понятия](/docs/api/ru/concepts.md): Интеграция, slug, токен, поля, островок, карточка, приоритет и срок жизни значений.
- [Типы полей](/docs/api/ru/fields.md): Как поля приводятся из строки CLI и из JSON, примеры push и тексты ошибок 422.
- [CLI sparku](/docs/api/ru/cli.md): Все команды sparku, их флаги, порядок поиска токена и коды выхода.
- [HTTP API](/docs/api/ru/http.md): Транспорт, авторизация и полный список маршрутов /v1 — запрос, тело, ответ, коды ошибок.
- [Кнопки и события](/docs/api/ru/events.md): Поток /events, at-most-once доставка, sparku listen в NDJSON и с --exec, другие действия кнопок.
- [Вопросы человеку](/docs/api/ru/dialogs.md): POST …/dialogs и sparku ask — варианты, подтверждение, таймаут, вложение; как агент спрашивает разрешения.
- [Файлы .sparku и импорт](/docs/api/ru/packages.md): Формат .sparku, что в него не входит, POST /v1/imports и sparku import, согласие человека, риски.
- [Рецепты](/docs/api/ru/recipes.md): Готовые примеры — прогресс деплоя, сборка Xcode, мониторинг сервера, таймер, очередь задач, подтверждение агента.
- [Если не работает](/docs/api/ru/troubleshooting.md): sparku doctor, типичные ошибки — от отсутствия сокета до 409, журнал запросов и консоль «Проверка».

## Optional

- [OpenAPI 3.1](/openapi.json): machine-readable /v1; `sparku openapi <slug>` prints the exact schema of one integration
- [Full docs, Russian](/llms-full.ru.txt): all Russian pages in one file
- [Human-readable page](/docs/api/)