Triangulation/docs/API.md

API Reference

Базовый URL: http://<listen_host>:<listen_port>

Контент ответов: application/json; charset=utf-8

GET /health

Проверка состояния сервиса.

200 OK

{
  "status": "ok",
  "updated_at_utc": "2026-03-02T12:34:56+00:00",
  "error": ""
}

503 Service Unavailable

{
  "status": "warming_up",
  "updated_at_utc": null,
  "error": "no data yet"
}

GET /result

Последний итоговый результат расчета.

200 OK

{
  "status": "ok",
  "updated_at_utc": "2026-03-02T12:35:01+00:00",
  "data": {
    "timestamp_utc": "2026-03-02T12:35:01+00:00",
    "selected_frequency_hz": 868100000.0,
    "selected_frequency_mhz": 868.1,
    "position": { "x": 1.2, "y": 2.3, "z": 0.4 },
    "rmse_m": 0.52,
    "frequency_table": []
  },
  "output_delivery": {
    "enabled": true,
    "status": "ok",
    "ok_count": 1,
    "error_count": 0,
    "skipped_count": 0,
    "servers": []
  }
}

503 Service Unavailable

{
  "status": "warming_up",
  "updated_at_utc": null,
  "error": "no data yet"
}

GET /frequencies

Таблица решений по частотам + статус доставки.

200 OK

{
  "status": "ok",
  "updated_at_utc": "2026-03-02T12:35:01+00:00",
  "selected_frequency_hz": 868100000.0,
  "selected_frequency_mhz": 868.1,
  "frequency_table": [
    {
      "frequency_hz": 433920000.0,
      "frequency_mhz": 433.92,
      "position": { "x": 1.0, "y": 2.0, "z": 0.3 },
      "rmse_m": 0.65,
      "exact": false
    }
  ],
  "output_delivery": {
    "enabled": true,
    "status": "partial"
  }
}

GET /config

Возвращает текущий конфиг.

Особенность:

• поле runtime.write_api_token редактируется в ответе (""),
• добавляется runtime.write_api_token_set (bool).

200 OK

{
  "status": "ok",
  "config_path": "config.json",
  "config": {
    "runtime": {
      "write_api_token": "",
      "write_api_token_set": true
    }
  }
}

POST /refresh

Принудительный запуск одного цикла опроса и расчета.

Тело запроса: {} (или любой JSON-объект).

Заголовки при включенном токене

• X-API-Token: <token> или
• Authorization: Bearer <token>

200 OK

{
  "status": "ok",
  "updated_at_utc": "2026-03-02T12:35:20+00:00"
}

401 Unauthorized

{
  "status": "error",
  "error": "unauthorized: missing or invalid API token"
}

500 Internal Server Error

{
  "status": "error",
  "error": "Output server(s) rejected payload: sink-a"
}

POST /config

Валидация и горячее применение нового конфига.

Ограничения:

• тело должно быть JSON-объектом,
• максимальный размер 1_000_000 байт.

Заголовки при включенном токене

• X-API-Token: <token> или
• Authorization: Bearer <token>

200 OK

{
  "status": "ok",
  "saved": true,
  "save_error": "",
  "restart_required": false,
  "applied": true,
  "config_path": "config.json"
}

400 Bad Request

{
  "status": "error",
  "error": "Config validation failed: input.receivers must contain at least 3 objects."
}

413 Payload Too Large

{
  "status": "error",
  "error": "Config payload too large: 1500000 bytes, max is 1000000"
}

401 Unauthorized

{
  "status": "error",
  "error": "unauthorized: missing or invalid API token"
}

UI и статические файлы

• GET / и GET /ui — веб-интерфейс.
• GET /static/* — JS/CSS.