Поддержка и загрузки

GET /api/v1/catalog/

Права: не требуются (достаточно любого валидного ключа или токена)

Справка «что умеет этот сервер»: версия API, имя узла, часовой пояс, список путей. Удобно проверить, что ключ работает.

{
  "version": "1.0",
  "server": {
    "id": 1,
    "name": "NVR-главный",
    "hostname": "192.168.1.10",
    "timezone": "Europe/Moscow"
  },
  "auth": "Bearer",
  "auth_note": "JWT от /auth/login/ или API-ключ (nvr_…) из Настройки → Система → API-ключи",
  "scopes": ["analytics:write", "bookmarks:read", "bookmarks:write", "cameras:read", "media:read", "streams:read", "webhooks:manage"],
  "endpoints": {
    "cameras": "https://192.168.1.10/api/v1/cameras/",
    "health": "https://192.168.1.10/api/v1/health/"
  }
}

• version — версия внешнего API.
• server — этот узел: внутренний id, отображаемое имя, хост, часовой пояс записей.
• auth — схема: всегда Bearer.
• scopes — все возможные права, которые можно выдать ключу.
• endpoints — готовые абсолютные URL основных методов (удобно для автодискавери).

GET /api/v1/health/

Права: не требуются

Проверка «жив ли сервер и стример». Мониторинг и heartbeat интеграций.

{
  "status": "ok",
  "app": true,
  "streamer": true,
  "server": { "id": 1, "name": "NVR-главный" }
}

• status — ok, если стример отвечает; иначе degraded (приложение работает, видео может быть недоступно).
• app — веб-приложение сервера отвечает.
• streamer — движок трансляции и записи доступен.
• server — id и имя локального узла.

POST /api/v1/auth/login/

Без ключа. Тело: логин и пароль пользователя с доступом к API

Вход пользователя (мобильное приложение, личный токен). Для серверных интеграций предпочтительнее API-ключ из настроек.

// запрос
{ "username": "operator", "password": "***" }

// ответ
{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

• access — короткоживущий токен: подставляйте в Authorization: Bearer ….
• refresh — токен обновления (см. следующий метод).

POST /api/v1/auth/refresh/

Без ключа. Тело: {"refresh": "…"}

Обновить access-токен, не спрашивая пароль заново.

{ "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

• access — новый токен доступа.

GET /api/v1/account/

Только токен пользователя (не API-ключ)

Профиль текущего пользователя — для приложений, где человек вошёл своим логином.

{
  "username": "operator",
  "email": "op@example.com",
  "first_name": "Иван",
  "last_name": "Петров",
  "last_login": "2026-10-27T10:15:00+03:00",
  "date_joined": "2026-01-10T09:00:00+03:00"
}

• username — логин.
• email, first_name, last_name — контакты и ФИО.
• last_login / date_joined — время последнего входа и регистрации (ISO).

Изменение профиля: PATCH /api/v1/account/ с полями email / имени; смена пароля — current_password + new_password.

GET /api/v1/account/login-logs/

Только токен пользователя

Последние входы этого пользователя (до 30 записей).

{
  "logs": [
    {
      "action": "auth.mobile.login",
      "message": "Вход: operator",
      "ip_address": "10.0.0.5",
      "created_at": "2026-10-27T10:15:00+03:00",
      "source": "mobile"
    }
  ]
}

• logs[] — массив событий входа.
• ip_address — откуда входили.
• source — канал (например mobile).
• created_at — когда.

GET /api/v1/cameras/

Scope: cameras:read. Параметры: ?group=, ?status=online|offline|unknown

Список активных камер — отправная точка любой интеграции.

[
  {
    "id": 12,
    "name": "Вход склад",
    "ip_address": "192.168.1.51",
    "is_active": true,
    "has_audio": true,
    "audio_enabled": false,
    "record_enabled": true,
    "record_mode": "continuous",
    "server_id": 1,
    "server_name": "NVR-главный",
    "status": { "overall": "online", "main": "online", "sub": "online" },
    "groups": [{ "id": 3, "name": "Склад" }],
    "whep_sub_url": "http://192.168.1.10:8889/cam12_sub/whep",
    "whep_main_url": "http://192.168.1.10:8889/cam12_main/whep",
    "created_at": "2026-03-01T12:00:00+03:00"
  }
]

• id — номер камеры в остальных запросах.
• name — название в интерфейсе.
• ip_address — IP устройства.
• record_enabled / record_mode — пишется ли архив и режим записи.
• status.overall — сводный статус потока: online / offline / unknown.
• groups — группы, в которые входит камера.
• whep_sub_url / whep_main_url — прямые WHEP URL суб- и основного потока (для клиентов, которые ходят к стримеру напрямую).

GET /api/v1/cameras/{id}/

Scope: cameras:read

Та же карточка, что в списке, но по одной камере. Ответ — один объект (не массив), поля те же.

GET /api/v1/groups/

Scope: cameras:read

Группы камер — чтобы фильтровать список или строить дерево в своём UI.

[
  {
    "id": 3,
    "name": "Склад",
    "description": "Камеры склада",
    "camera_count": 8
  }
]

• id — для фильтра /cameras/?group=3.
• name / description — название и описание.
• camera_count — сколько камер в группе.

GET /api/v1/cameras/{id}/streams/?quality=sub

Scope: streams:read. quality: main или sub (по умолчанию sub)

Готовые ссылки на живой поток выбранного качества — для плеера, SOC или стороннего клиента.

{
  "camera_id": 12,
  "live": {
    "quality": "sub",
    "whep": "http://192.168.1.10:8889/cam12_sub/whep",
    "rtsp": "rtsp://192.168.1.10:8554/cam12_sub",
    "hls": "http://192.168.1.10:8888/cam12_sub/index.m3u8"
  }
}

• live.whep — WebRTC (WHEP): низкая задержка в браузере.
• live.hls — HLS-плейлист для совместимых плееров.
• live.rtsp — RTSP для VLC / профессиональных клиентов.
• live.quality — какое качество вы запросили.

POST /api/v1/cameras/{id}/whep/?quality=sub

Scope: streams:read. Тело: SDP offer, Content-Type: application/sdp

Проксирование WHEP через сервер (удобно для мобильных клиентов за NAT). Ответ — не JSON, а SDP answer (текст) и служебные заголовки сессии.

// ответ (тело): SDP answer
v=0
o=- 0 0 IN IP4 192.168.1.10
...
a=ice-ufrag:...

• Тело ответа — SDP для установки WebRTC.
• Заголовки сессии (например Link) нужны, чтобы потом закрыть поток через DELETE на тот же путь.
• При ошибке — JSON {"detail": "…"} и код 4xx/5xx.

Закрытие сессии: DELETE /api/v1/cameras/{id}/whep/?quality=sub.

GET /api/v1/cameras/{id}/recordings/?from=&to=&limit=

Scope: streams:read

Список сегментов архива за период (ISO-даты в from/to).

{
  "camera_id": 12,
  "segments": [
    {
      "filename": "2026-10-27_14-00-00.mp4",
      "started_at": "2026-10-27T14:00:00+03:00",
      "ended_at": "2026-10-27T14:05:00+03:00",
      "duration_sec": 300,
      "file_size": 52428800,
      "get": "/api/playback/cameras/12/stream/?at=..."
    }
  ]
}

• segments[] — куски записи на диске.
• started_at / ended_at — границы сегмента.
• duration_sec — длина в секундах.
• file_size — размер файла в байтах.
• get — путь к потоковой выдаче сегмента (внутренний URL сервера).

GET /api/v1/cameras/{id}/playback/segments/?from=&to=

Scope: streams:read

То же, что записи, плюс движение и маркеры на шкале — для построения таймлайна в своём плеере.

{
  "camera_id": 12,
  "segments": [ /* как выше */ ],
  "motion": [
    { "started_at": "2026-10-27T14:02:10+03:00", "ended_at": "2026-10-27T14:02:45+03:00" }
  ],
  "markers": [
    { "at": "2026-10-27T14:03:00+03:00", "type": "bookmark", "label": "Проход" }
  ]
}

• motion — интервалы, где в архиве отмечено движение.
• markers — точки на шкале (закладки и др.).

GET /api/v1/cameras/{id}/playback/?at=2026-10-27T14:05:00Z&duration=60

Scope: streams:read. Обязателен at (момент времени). duration — секунды клипа (по умолчанию 60). quality: main|sub

Метаданные воспроизведения «с этого момента»: какой сегмент найден и куда качать клип.

{
  "camera_id": 12,
  "segment": {
    "filename": "2026-10-27_14-00-00.mp4",
    "started_at": "2026-10-27T14:00:00+03:00",
    "ended_at": "2026-10-27T14:05:00+03:00"
  },
  "playback": {
    "get": "/api/v1/cameras/12/playback/stream/?at=2026-10-27T14:05:00Z&duration=60&quality=main",
    "clip_method": "mediamtx",
    "start": "2026-10-27T14:05:00+00:00",
    "duration": 60
  }
}

• segment — файл архива, в который попал запрошенный момент (или null, если записи нет).
• playback.get — URL бинарного клипа (см. следующий метод).
• playback.clip_method — как сервер отдаст клип (стример или сборка с диска).

GET /api/v1/cameras/{id}/playback/stream/?at=…&duration=300

Scope: streams:read. Ответ — файл video/mp4, не JSON

Скачать или стримить клип начиная с момента at. Поддерживается HTTP Range.

// заголовки ответа (пример)
Content-Type: video/mp4
X-Clip-Method: mediamtx

// тело — бинарный MP4

• При успехе — поток видео.
• X-Clip-Method — способ сборки клипа.
• Если записи нет — JSON {"detail": "Запись не найдена…"} и код 404.

GET /api/v1/playback/events/?from=&to=&camera_id=&types=

Scope: streams:read

События на шкале архива по одной камере или по всем доступным: движение, закладки, аналитика и т.п.

{
  "events": [
    {
      "camera_id": 12,
      "at": "2026-10-27T14:05:00+03:00",
      "type": "bookmark",
      "label": "Проход у входа"
    }
  ]
}

• events[] — точки/интервалы для таймлайна.
• type — вид события (зависит от источников на сервере).
• camera_id — к какой камере относится.
• Фильтр types — список через запятую; limit — до 500.

POST /api/v1/cameras/{id}/photo/

Scope: media:read. Тело не обязательно. Ответ — JPEG

Сделать снимок с живого потока камеры «прямо сейчас» (для СКУД, отчётов, чат-ботов).

// заголовки
Content-Type: image/jpeg

// тело — бинарный JPEG

• Успех — картинка JPEG.
• Ошибка захвата — JSON {"detail": "…"} и код 502.
• При настроенных webhook’ах уйдёт событие photo.ready.

GET /api/v1/cameras/{id}/bookmarks/?from=&to=&limit=

Scope: bookmarks:read

Список закладок на архиве камеры.

[
  {
    "id": 401,
    "camera_id": 12,
    "marked_at": "2026-10-27T14:05:00+03:00",
    "message": "Проход у входа",
    "source": "api",
    "metadata": {},
    "created_at": "2026-10-27T14:05:01+03:00",
    "playback_path": "/api/v1/cameras/12/playback/?at=2026-10-27T14:05:00+03:00"
  }
]

• marked_at — момент на шкале.
• message — текст закладки.
• source — откуда создана: api, ui, mqtt, analytics.
• playback_path — готовый путь к воспроизведению с этого момента.

POST /api/v1/cameras/{id}/bookmarks/

Scope: bookmarks:write

Поставить закладку «сейчас минус N секунд» — например, когда СКУД зафиксировал проход.

// запрос
{
  "offset_seconds": 2,
  "message": "Карта 4821",
  "metadata": { "card": "4821" }
}

// ответ — та же структура, что у GET (код 201)

• offset_seconds — сдвиг назад от текущего времени сервера (0…86400).
• message или event — текст.
• metadata — произвольный JSON для вашей системы.

POST /api/v1/analytics/events/

Scope: analytics:write

Записать детекцию внешней аналитики или СКУД в журнал сервера. Событие появится на шкале; опционально создаётся закладка; уходят webhook’и и сценарии автоматизации.

// запрос
{
  "camera_id": 12,
  "detected_at": "2026-10-27T14:05:00+03:00",
  "type": "person",
  "confidence": 0.91,
  "bbox": [0.1, 0.2, 0.4, 0.7],
  "create_bookmark": true,
  "bookmark_message": "Человек у входа",
  "payload": { "tracker_id": 77 }
}

// ответ (201)
{
  "id": 9001,
  "camera_id": 12,
  "detected_at": "2026-10-27T14:05:00+03:00",
  "type": "person",
  "confidence": 0.91,
  "bbox": [0.1, 0.2, 0.4, 0.7],
  "snapshot_url": "",
  "payload": { "tracker_id": 77 },
  "created_at": "2026-10-27T14:05:00.120+03:00",
  "bookmark": {
    "id": 402,
    "camera_id": 12,
    "marked_at": "2026-10-27T14:05:00+03:00",
    "message": "Человек у входа",
    "source": "analytics",
    "playback_path": "/api/v1/cameras/12/playback/?at=2026-10-27T14:05:00+03:00"
  }
}

• camera_id — на какую камеру повесить событие.
• detected_at — время детекции (ISO).
• type — тип: person, vehicle, face… — строка до 64 символов.
• confidence — уверенность 0…1 (необязательно).
• bbox — рамка [x1, y1, x2, y2] в долях кадра 0…1.
• create_bookmark — если true, в ответе будет объект bookmark.
• payload — любые доп. поля вашей системы.

GET / POST /api/v1/webhooks/

Scope: webhooks:manage

Подписки: сервер сам POST’ит JSON на ваш URL при событиях.

// POST запрос
{
  "url": "https://scs.example/hooks/nvr",
  "secret": "shared-secret",
  "events": ["bookmark.created", "analytics.detection", "camera.status.changed"],
  "is_active": true
}

// ответ (201)
{
  "id": 5,
  "url": "https://scs.example/hooks/nvr",
  "events": ["bookmark.created", "analytics.detection", "camera.status.changed"],
  "is_active": true,
  "created_at": "2026-10-27T12:00:00+03:00"
}

• url — куда слать уведомления.
• events — список: camera.status.changed, bookmark.created, recording.segment.closed, photo.ready, analytics.detection, device.input.triggered, alarm.triggered.
• secret — общий секрет для проверки подписи (если настроен на вашей стороне).
• is_active — включена ли подписка.

Изменение: PATCH /api/v1/webhooks/{id}/. Удаление: DELETE /api/v1/webhooks/{id}/ (пустой ответ 204).

GET /api/v1/mqtt/config/

Scope: cameras:read

Если на сервере включён MQTT — префикс топиков и имена каналов для статуса, закладок и команд.

{
  "enabled": true,
  "site_id": "site-01",
  "topic_prefix": "nvrcloud/site-01",
  "topics": {
    "status": "nvrcloud/site-01/cameras/{camera_id}/status",
    "bookmarks": "nvrcloud/site-01/cameras/{camera_id}/bookmarks",
    "analytics": "nvrcloud/site-01/cameras/{camera_id}/analytics",
    "commands_bookmark": "nvrcloud/site-01/commands/bookmark",
    "commands_photo": "nvrcloud/site-01/commands/photo"
  },
  "broker_configured": true
}

• enabled — включён ли MQTT на этом сервере.
• topic_prefix — корень всех топиков площадки.
• topics — шаблоны; подставьте id камеры вместо {camera_id}.
• broker_configured — задан ли адрес брокера.

Проверка брокера: GET /api/v1/mqtt/health/ → status ok/disabled/error и флаг connected.