# Обзор

> Что такое открытый API SparkU и для чего скрипты выводят данные на островок.

## Что это

Открытый API SparkU — способ показать на островке (вырезе экрана) данные, которые
собирает **ваш собственный скрипт или программа**: прогресс сборки, метрики сервера,
таймер, очередь задач. Скрипт не рисует интерфейс — он только присылает значения в
готовые слоты, которые вы сами настроили заранее.

Типичные сценарии:

- **CI/деплой** — этап пайплайна, ветка, ссылка на сборку, кнопка «Открыть логи».
- **Сборки** — процент, стадия, сколько осталось.
- **Мониторинг сервера** — CPU, память, задержка, статус «работает / тормозит / лежит».
- **Таймеры** — обратный отсчёт до конца встречи, чайника, бэкапа.
- **ИИ-агенты спрашивают человека** — агент присылает вопрос с вариантами ответа и
  ждёт, пока вы нажмёте на островке.

## Модель: человек описывает форму, скрипт заполняет её

```
 Настройки → Свои интеграции                 скрипт / программа
 ┌───────────────────────────────┐           │ sparku push deploy progress=0.7
 │ «Деплой»  адрес: deploy       │           │ curl --unix-socket … /v1/…
 │ поля:  title, progress, stage │           ▼
 │ индикатор, строка, карточка   │      ~/.sparku/run/api.sock
 │ кнопки, приоритет, срок жизни │           ▼
 └──────────────┬────────────────┘     значения полей
                └──────────────────►  элементы островка
```

**Интеграцию** — название, адрес (slug), поля и то, как они выглядят на островке, —
создаёт только человек: руками в редакторе, мастером по заготовке или импортом файла
`.sparku` с явным согласием. Скрипт получает адрес и токен и с этого момента может
только **записывать значения** в уже существующие поля. Добавить новый элемент,
кнопку или карточку скрипт не может — состав островка неизменен, меняется только
содержимое.

> [!WARNING]
> Свои интеграции — экспериментальная функция. Она может вести себя непредсказуемо
> (карточки и островок иногда отображаются не так, как задумано), а частые обновления
> из скриптов повышают расход процессора и батареи. Функция выключена по умолчанию —
> включить её нужно осознанно в Настройках, прочитав предупреждение.

## Только локально, без сети

API работает через UNIX-сокет `~/.sparku/run/api.sock` и существует, только пока
функция включена в настройках. Сетевого порта нет: писать в интеграцию может любая
программа **на этом же Mac**, запущенная от вашего имени, — то есть то же самое, что
может делать любой ваш скрипт и так. Токен нужен для адресации и защиты от опечаток и
чужих скриптов, а не как граница доступа между процессами одного пользователя.

## Дальше

- [Быстрый старт](/docs/api/ru/quickstart.md) — включить функцию, поставить CLI, отправить
  первое значение.
- [Понятия](/docs/api/ru/concepts.md) — интеграция, slug, токен, поля, элементы островка и
  карточки, приоритет, срок жизни значений.
- [Типы полей](/docs/api/ru/fields.md) — что и как присылать в `push`, тексты ошибок.
- [CLI sparku](/docs/api/ru/cli.md) — все команды, флаги, коды выхода.