Управление локальным агентом

Локальный HTTP API позволяет программно управлять приложением CogniRec — десктопной программой для записи звука. Через него можно запускать и останавливать запись, а также получать текущий статус.

Включение API

По умолчанию API выключен. Чтобы его включить:

1. Найдите файл settings.json:

   • Windows: %LOCALAPPDATA%\CogniRec\settings.json
   • macOS: ~/Library/Application Support/CogniRec/settings.json
   • Linux: ~/.local/share/CogniRec/settings.json

2. В блоке control_server поставьте "enabled": true:

   {
     "control_server": {
       "enabled": true,
       "port": 19100,
       "token": "your-token-here"
     }
   }

3. Перезапустите CogniRec.

Токен генерируется автоматически при первом запуске приложения. Порт по умолчанию — 19100; если он занят, приложение выберет случайный порт в диапазоне 19001–19999 и запишет его в settings.json.

Аутентификация

Все методы (кроме /api/health) требуют передачи токена одним из способов:

• Заголовок (рекомендуется): Authorization: Bearer <token>
• Query-параметр: ?token=<token>

Токен берётся из поля control_server.token в settings.json.

Методы

Проверка доступности

GET /api/health

Не требует аутентификации.

Ответ:

{ "status": "ok" }

---

Статус записи

GET /api/recording/status

Ответ:

{
  "is_recording": false,
  "duration_sec": 0
}

Поле	Тип	Описание
is_recording	boolean	Идёт ли запись в данный момент
duration_sec	number	Длительность текущей записи в секундах (0, если не записывает)

---

Запуск записи

POST /api/recording/start

Если запись уже идёт, вернёт успешный ответ с "message": "already recording".

Ответ:

{ "message": "recording started" }

---

Остановка записи

POST /api/recording/stop

Если запись не идёт, вернёт успешный ответ с "message": "not recording".

Ответ:

{ "message": "recording stopped" }

Ошибки

При ошибке ответ содержит описание в поле error:

{ "error": "описание ошибки" }

HTTP-код	Причина
401	Неверный или отсутствующий токен
405	Неверный HTTP-метод (например, GET вместо POST)
500	Внутренняя ошибка (не удалось запустить/остановить запись)

Примеры

curl

TOKEN="ваш-токен-из-settings-json"

# Проверить доступность
curl http://127.0.0.1:19100/api/health

# Получить статус
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:19100/api/recording/status

# Запустить запись
curl -X POST -H "Authorization: Bearer $TOKEN" http://127.0.0.1:19100/api/recording/start

# Остановить запись
curl -X POST -H "Authorization: Bearer $TOKEN" http://127.0.0.1:19100/api/recording/stop

Python

import requests

BASE = "http://127.0.0.1:19100"
TOKEN = "ваш-токен-из-settings-json"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# Запустить запись
requests.post(f"{BASE}/api/recording/start", headers=HEADERS)

# Проверить статус
r = requests.get(f"{BASE}/api/recording/status", headers=HEADERS)
print(r.json())  # {"is_recording": true, "duration_sec": 5}

# Остановить запись
requests.post(f"{BASE}/api/recording/stop", headers=HEADERS)