Камеры

Создание и изменение камер, массовые операции, ONVIF, PTZ, доступ к видео и архиву.

Камера — центральный объект системы: она принадлежит организации, размещена на ноде, несёт один или несколько профилей (потоков), может писать архив, отдаваться операторам и раздаваться по ссылке. Здесь собраны все маршруты, работающие с камерами, включая ONVIF, PTZ и шаблоны камер.

Все запросы требуют заголовка Authorization: Bearer $TOKEN. Базовый URL, получение токена, общий формат ошибок и правила пагинации — в разделе Введение и аутентификация.

В примерах используются переменные BASE=https://cctv.example.com и TOKEN, а адрес камеры показан как 192.0.2.10 — это адрес из диапазона, зарезервированного под документацию; подставьте свой.

Что нужно знать до первого запроса#

Три списка камер — и почему их три#

Оператору первый маршрут закрыт (403 not_admin) — именно поэтому существуют два других. Пароль камеры не входит ни в один список и ни в одну карточку: его отдаёт единственный маршрут GET /api/v1/cameras/{id}/credentials.

Фильтры ?tag= (один uuid или несколько через запятую — камера должна нести все перечисленные теги) и ?status= (тот же словарь problem|offline|error|live|parked) действуют одинаково и на административном GET /cameras, и на мобильном GET /mobile/cameras — форма параметров общая.

Жёсткие ограничения, действующие всегда: не более 32 тегов на камеру, не более 4 профилей на камеру, не более 500 идентификаторов в пакетной операции, не более 50 камер в одной подписке на поток статусов.

Общие структуры#

Объект камеры#

Эта структура «расплющена» внутрь строк списка и внутрь ответа с деталями камеры.

{
  "id": "<UUID>", "org_id": "<UUID>", "node_id": "<UUID>",
  "name": "Вход, главный холл",
  "enabled": true,
  "use_onvif": true, "onvif_events_enabled": false,
  "ptz_pan_tilt": true, "ptz_zoom": true,
  "tunnel": null,
  "host": "192.0.2.10", "onvif_port": 80,
  "make": null, "model": null, "serial": null, "firmware": null,
  "username": "operator",
  "dvr_mode": "duration", "dvr_value": 604800, "dvr_storage": "dvr1",
  "dvr_copy_storage": null, "dvr_copy_bucket": null,
  "dvr_copy_mode": "none", "dvr_copy_value": null,
  "dvr_prune_without_events": false, "dvr_event_grace_seconds": 1800,
  "mosaic_transport": "mse-ws", "mosaic_profile": "main", "mosaic_allow_switch": false,
  "interval_timeout_secs": null,
  "notes": "",
  "created_at": "2026-08-18T10:00:00Z", "updated_at": "2026-08-18T10:00:00Z"
}

Профиль#

Профиль — это один поток камеры. У камеры от одного до четырёх профилей, и ровно один из них обязан иметь kind: "main".

{ "id": "<UUID>", "kind": "main", "source": "manual",
  "rtsp_url": "rtsp://operator:пароль@192.0.2.10:554/stream1",
  "onvif_profile_token": null, "onvif_stream_uri": null,
  "mode": "always",
  "width": 1920, "height": 1080, "codec": "h264", "fps": 25.0 }

• kind — произвольный идентификатор потока по маске ^[a-z0-9_]{1,16}$, уникальный в пределах камеры. По соглашению main — основной поток, sub — вспомогательный (для мозаик и превью).
• source — manual (ссылка задана руками) или onvif (ссылку получает Plane с устройства).
• mode вычисляется, а не задаётся: у main всегда always, у остальных — on_demand (поток поднимается только когда кто-то смотрит).
• onvif_stream_uri заполняется после успешного POST /api/v1/cameras/{id}/onvif/resolve.

Живой статус камеры#

Поле live_status в административном списке и в мобильной витрине вычисляется по строгому приоритету:

Камеры#

GET /api/v1/cameras#

Администратор — суперадмин видит всю установку или одну организацию через ?org=, администратор организации — только свою.

Назначение — административный список камер: строка камеры, имя и состояние ноды, теги, признак наличия источника и живой статус.

Параметры запроса

Значения status разворачиваются так (снимок состояния берётся один раз до запроса, поэтому страница не может противоречить фильтру):

Пример curl

curl -sS "$BASE/api/v1/cameras?limit=100&status=problem" \
  -H "Authorization: Bearer $TOKEN"

Пример ответа

{
  "rows": [
    {
      "id": "<UUID>", "org_id": "<UUID>", "node_id": "<UUID>",
      "name": "Вход, главный холл", "enabled": true,
      "host": "192.0.2.10", "dvr_mode": "duration", "dvr_value": 604800,
      "node_name": "node-1", "node_state": "active", "node_disabled": false,
      "tags": ["<UUID>"], "has_source": true,
      "live_status": "failing", "connected_since_ms": null, "reconnects": 17
    }
  ],
  "next": null
}

Строка — это объект камеры плюс поля списка: node_name, node_state (pending | active | retired), node_disabled, tags (массив идентификаторов тегов), has_source, live_status, connected_since_ms, reconnects.

has_source — это статическая настройка, а не признак работоспособности: он равен true, если хоть у одного профиля есть rtsp_url либо разрешённый адрес ONVIF.

Ошибки

Примечания

• ?status= с пустым значением — это не «фильтр не задан», а недопустимое значение: приходит 400 bad_camera_status. Чтобы отключить фильтр, уберите параметр целиком.
• Корректный статус, под который ничего не подошло, возвращает {"rows":[],"next":null} с кодом 200 — это не ошибка.
• Поиск q не экранирует % и _; подробнее — в разделе Введение.

POST /api/v1/cameras#

Администратор — суперадмин может создать камеру в любой организации через org_id, администратор организации — только в своей.

Назначение — создать камеру вместе с профилями и тегами. Проверяются квота организации, ноды и хранилища по фактическому состоянию флота; камера, профили и теги записываются одной транзакцией, после чего запускается применение конфигурации на ноде.

Тело запроса. Обязательны только name и profiles; остальное имеет значения по умолчанию.

Основное

Размещение

node_auto и node_id взаимоисключающи, и одно из них обязательно: указать оба или ни одного — 400 camera_node_choice. Камера не может существовать «без размещения».

Устройство, ONVIF и PTZ

Архив

Отображение в мозаике

Профили (profiles, обязательное поле, от 1 до 4 элементов, ровно один main)

Туннель (tunnel, объект | null) — для камеры из закрытой сети: {agent_id, device_id, rtsp_lease_id, onvif_lease_id}. Требует use_onvif: true и непустых учётных данных. У такой камеры host и onvif_port перезаписываются адресом релея — то, что вы прислали, игнорируется. См. Камеры за NAT: туннели.

Пример curl — камера с двумя потоками, учётными данными и в полях, и в ссылке, с адресом устройства и недельным архивом:

curl -sS -X POST "$BASE/api/v1/cameras" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Вход, главный холл",
    "node_auto": true,
    "host": "192.0.2.10",
    "onvif_port": 80,
    "use_onvif": true,
    "username": "operator",
    "password": "ПАРОЛЬ-КАМЕРЫ",
    "dvr_mode": "duration",
    "dvr_value": 604800,
    "dvr_storage": "dvr1",
    "tags": ["<UUID>"],
    "profiles": [
      { "kind": "main", "source": "manual",
        "rtsp_url": "rtsp://operator:ПАРОЛЬ-КАМЕРЫ@192.0.2.10:554/stream1" },
      { "kind": "sub", "source": "manual",
        "rtsp_url": "rtsp://operator:ПАРОЛЬ-КАМЕРЫ@192.0.2.10:554/stream2" }
    ]
  }'

curl -sS "$BASE/api/v1/cameras?q=главный" -H "Authorization: Bearer $TOKEN" \
  | python3 -c '
import sys, json
for r in json.load(sys.stdin)["rows"]:
    print(r["name"], "host =", r["host"] or "(ПУСТО — ONVIF и PTZ работать не будут)")'

Пример ответа — 201 Created, объект камеры плюс node_name, node_state, node_storage_names, profiles, tags:

{
  "id": "<UUID>", "org_id": "<UUID>", "node_id": "<UUID>",
  "name": "Вход, главный холл", "enabled": true,
  "host": "192.0.2.10", "onvif_port": 80, "use_onvif": true,
  "username": "operator",
  "dvr_mode": "duration", "dvr_value": 604800, "dvr_storage": "dvr1",
  "node_name": "node-1", "node_state": "active",
  "node_storage_names": ["dvr1", "dvr2"],
  "profiles": [
    { "id": "<UUID>", "kind": "main", "source": "manual",
      "rtsp_url": "rtsp://operator:ПАРОЛЬ-КАМЕРЫ@192.0.2.10:554/stream1",
      "mode": "always" },
    { "id": "<UUID>", "kind": "sub", "source": "manual",
      "rtsp_url": "rtsp://operator:ПАРОЛЬ-КАМЕРЫ@192.0.2.10:554/stream2",
      "mode": "on_demand" }
  ],
  "tags": ["<UUID>"]
}

Ошибки

Примечания

• Если у организации режим размещения force_auto, автоподбор применяется даже при node_auto: false.
• При достижении 80 % и 100 % лимита камер система создаёт служебное событие о квоте.
• Логин и пароль из полей username/password нода подставляет в источник сама; вписанные прямо в rtsp_url учётные данные она оставляет как есть. Поле host не заполняется ни из того, ни из другого.

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

Администратор — камера должна принадлежать доступной организации.

Назначение — полные сведения об одной камере, включая профили и теги.

Параметры пути — id (uuid) — камера.

Пример curl

curl -sS "$BASE/api/v1/cameras/<UUID>" -H "Authorization: Bearer $TOKEN"

Пример ответа — та же структура, что возвращает создание камеры.

Ошибки

Примечания — node_storage_names равно null, пока нода ни разу не сообщила свой список хранилищ. Это не ошибка, а «данных ещё нет».

PATCH /api/v1/cameras/{id}#

Администратор

Назначение — частичное изменение камеры. Скалярные поля правятся на месте; profiles и tags, если они переданы, заменяют весь набор целиком.

Параметры пути — id (uuid).

Тело запроса. Все поля необязательны, но ведут себя по-разному:

Пропуск оставляет значение; null не принимается как очистка: name, enabled, node_auto, node_id, use_onvif, onvif_events_enabled, ptz_pan_tilt, ptz_zoom, username, password, dvr_mode, dvr_copy_mode, dvr_prune_without_events, dvr_event_grace_seconds, mosaic_transport, mosaic_profile, mosaic_allow_switch, notes.

Пропуск оставляет значение; null очищает поле: host, onvif_port, make, model, serial, firmware, dvr_value, dvr_storage, dvr_copy_storage, dvr_copy_bucket, dvr_copy_value, interval_timeout_secs.

Замена набора целиком (пропуск оставляет как было): profiles — массив профилей, проверяется заново и по-прежнему должен содержать ровно один main; tags — массив идентификаторов, не более 32, пустой массив снимает все теги.

Полей org_id и tunnel в этом запросе нет: перенос камеры в другую организацию делается через POST /api/v1/cameras/{id}/copy, привязка туннеля — при создании.

Пример curl — сменить имя, добавить адрес устройства и очистить бакет холодной копии:

curl -sS -X PATCH "$BASE/api/v1/cameras/<UUID>" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Вход, главный холл (запад)",
    "host": "192.0.2.10",
    "dvr_copy_bucket": null
  }'

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

Ошибки — все проверки создания, а также:

Примечания

• dvr_mode: "none" сам очищает dvr_storage, сбрасывает dvr_prune_without_events в false и отключает всю политику холодной копии — обнулять эти поля вручную не нужно.
• Приведение mosaic_profile/mosaic_allow_switch к наличию профиля sub, которое делается при создании, здесь не повторяется: значения проверяются только на принадлежность перечислению.
• При замене набора профилей уже разрешённый адрес ONVIF сохраняется, если источник профиля не изменился, — удаление sub не «гасит» работающий main.
• Каждое успешное изменение поднимает версию конфигурации и вызывает применение на ноде.

DELETE /api/v1/cameras/{id}#

Администратор

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

Параметры пути — id (uuid).

Пример curl

curl -sS -X DELETE "$BASE/api/v1/cameras/<UUID>" -H "Authorization: Bearer $TOKEN"

Пример ответа

{ "id": "<UUID>", "deleted": true }

Ошибки

Примечания

• События камеры и их вложения намеренно остаются до истечения своего срока хранения; в очередь удаления ставятся только записи архива. Обработчик дожидается возвращения ноды в строй, если она была недоступна, и завершает удаление, лишь убедившись, что архив пуст.
• Ответ приходит сразу — фактическое освобождение диска происходит позже.

POST /api/v1/cameras/bulk#

Администратор — право на каждую камеру проверяется отдельно.

Назначение — применить одно действие к множеству камер одной транзакцией: удалить, включить/выключить, добавить или снять теги.

Тело запроса

Варианты action:

Пример curl — выключить три камеры:

curl -sS -X POST "$BASE/api/v1/cameras/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": ["<UUID>", "<UUID>", "<UUID>"],
    "action": { "kind": "set_enabled", "enabled": false }
  }'

Пример ответа

{ "affected": 2 }

Ошибки

Примечания

• affected — это число реально изменённых камер, а не размер ids. Камера, уже находившаяся в требуемом состоянии (уже выключена, уже с этим тегом), в счётчик не попадает. affected меньше длины списка — норма, а не признак частичного применения: частичного применения не бывает.
• delete и set_enabled меняют конфигурацию нод и вызывают её применение; операции с тегами применение не вызывают — ноды теги не читают.
• Каждая затронутая камера получает собственную запись аудита с пометкой о пакетном режиме.

POST /api/v1/cameras/{id}/copy#

Администратор — нужны права и на исходную организацию, и на организацию назначения.

Назначение — создать новую камеру, скопировав настройки существующей, при необходимости в другую организацию. Это единственная поддерживаемая межорганизационная операция с камерой.

Параметры пути — id (uuid) — камера-источник.

Тело запроса

Ровно одно из node_auto/node_id обязано быть задано. Если источник пишет архив, то ровно одно из storage_auto/storage тоже обязано быть задано; если источник архив не пишет, оба должны отсутствовать.

Пример curl

curl -sS -X POST "$BASE/api/v1/cameras/<UUID>/copy" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "org_id": "<UUID>",
    "name": "Вход, главный холл (копия)",
    "node_auto": true,
    "storage_auto": true
  }'

Пример ответа — 201 Created, новая камера в том же виде, что и при создании (обратите внимание: "enabled": false).

Ошибки — все ошибки создания камеры, а также:

Примечания

• Копируется: учётные данные (на стороне сервера, наружу они не отдаются), профили с их токенами ONVIF и метаданными, адрес, порт, справочные поля, режим и глубина архива, политика очистки по событиям, настройки мозаики, тайм-аут простоя, заметки, флаги ONVIF и PTZ.
• Не копируется: теги (копия создаётся без тегов), события, история архива, ссылки доступа, привязка к туннелю и вся политика холодной копии S3 — она сбрасывается намеренно, чтобы новый арендатор не начал писать в чужой бакет.
• Копия создаётся выключенной (enabled: false). Проверьте её и включите отдельным запросом.

GET /api/v1/cameras/lite#

Любой вошедший — оператор видит ровно те камеры, события которых ему разрешено читать (бит EVENTS); администратор организации — свою организацию; суперадмин — всю установку или одну организацию через ?org=.

Назначение — минимальный список камер для выпадающих фильтров. Существует потому, что административный список оператору недоступен.

Параметры запроса

Пример curl

curl -sS "$BASE/api/v1/cameras/lite?q=холл&limit=100" \
  -H "Authorization: Bearer $TOKEN"

Пример ответа

{ "rows": [ { "id": "<UUID>", "name": "Вход, главный холл" } ] }

Ошибки

Примечания — сортировка по имени, затем по идентификатору; курсора нет, это одна ограниченная страница. В теле только id и name — ни адреса, ни ноды, ни учётных данных здесь появиться не может. Оператор без грантов получит {"rows":[]}.

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

Администратор

Назначение — показать логин и пароль камеры в открытом виде. Это единственный маршрут, отдающий пароль.

Параметры пути — id (uuid).

Пример curl

curl -sS "$BASE/api/v1/cameras/<UUID>/credentials" -H "Authorization: Bearer $TOKEN"

Пример ответа

{ "username": "operator", "password": "ПАРОЛЬ-КАМЕРЫ" }

Ошибки

Доступ к видео и архиву#

Три маршрута ниже не передают видео. Они возвращают дескриптор: с какой ноды забирать поток и какие элементы управления показывать. Медиа затем идёт из браузера прямо на ноду, а нода самостоятельно проверяет права ещё раз.

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

Любой вошедший — принимается либо обычный токен сессии, либо токен ссылки общего доступа, выданной на эту камеру.

Назначение — дескриптор живого просмотра одной камеры.

Параметры пути — id (uuid).

Пример curl

curl -sS "$BASE/api/v1/cameras/<UUID>/play" -H "Authorization: Bearer $TOKEN"

Пример ответа

{
  "position": 0,
  "camera_id": "<UUID>",
  "name": "Вход, главный холл",
  "sub_path": "cam/<UUID>/sub",
  "accessible": true,
  "live": true,
  "has_sub": true,
  "media_base": "https://node.example.com:8443",
  "availability": "ready",
  "main_on_demand": false,
  "sub_on_demand": true,
  "mosaic_transport": "mse-ws",
  "mosaic_profile": "sub",
  "mosaic_allow_switch": true,
  "tags": [],
  "ptz": false, "ptz_pan_tilt": false, "ptz_zoom": false, "ptz_set_preset": false,
  "events": true
}

Значения availability:

Ошибки

Примечания

• media_base непуст только когда live: true и камера в состоянии ready. Пустой media_base — это защита: клиенту незачем открывать соединение, на которое у него нет прав.
• Вызывающий с одним лишь PREVIEW получает accessible: true, live: false, availability: "preview_only" и пустой media_base — то есть кадр, а не поток.
• По ссылке общего доступа ptz всегда false: ссылка — медиа-принципал, она не может управлять камерой.
• mosaic_allow_switch в ответе дополнительно ограничен наличием профиля sub, даже если в настройках камеры стоит true.
• Поля ptz* и events — подсказки для интерфейса. Реальную проверку выполняют сами маршруты PTZ и событий.

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

Любой вошедший — сессия либо токен ссылки на эту камеру.

Назначение — дескриптор архива: где лежит таймлайн и какие элементы управления архивом показать.

Параметры пути — id (uuid).

Пример curl

curl -sS "$BASE/api/v1/cameras/<UUID>/archive" -H "Authorization: Bearer $TOKEN"

Пример ответа

{
  "camera_id": "<UUID>",
  "name": "Вход, главный холл",
  "dvr_path": "cam/<UUID>/main",
  "media_base": "https://node.example.com:8443",
  "events": true,
  "export": false,
  "export_max_span_ms": 900000
}

Ошибки

Примечания

• Три независимых права. DVR — пропуск: без него дескриптор не выдаётся вовсе. EVENTS включает только отметки событий на таймлайне. EXPORT включает только кнопку выгрузки. Обладатель одного лишь DVR смотрит архив без отметок и без выгрузки.
• Архив всегда пишется с профиля main — dvr_path всегда оканчивается на /main и никогда не указывает на sub.
• Пустой media_base означает, что нода не активна или у неё нет публичного адреса. Показывайте честное «архив недоступен», а не повторяйте запрос в цикле.
• export_max_span_ms — действующий предел длительности одного фрагмента, по умолчанию 900 000 мс (15 минут); настраивается на Plane в пределах от 60 секунд до 24 часов.

POST /api/v1/cameras/{id}/export#

Любой вошедший — плюс бит EXPORT на эту камеру. Токен ссылки общего доступа здесь не принимается, только сессия.

Назначение — разрешить и записать в аудит выгрузку фрагмента архива, вернув адрес на ноде, откуда браузер скачает файл. Сам файл через Plane не идёт.

Параметры пути — id (uuid).

Тело запроса

Пример curl — последние 10 минут:

now=$(( $(date +%s) * 1000 ))
curl -sS -X POST "$BASE/api/v1/cameras/<UUID>/export" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"from\": $(( now - 600000 )), \"to\": $now}"

Пример ответа

{
  "url": "https://node.example.com:8443/cam/<UUID>/main/clip-1755000000-600.mp4",
  "from": 1755000000000,
  "to": 1755000600000
}

Ошибки

Примечания

• В возвращённом адресе нет учётных данных. Клиент обязан дописать свой токен: "$url?token=$TOKEN". Нода проверит бит EXPORT ещё раз, уже на самом файле.
• Адрес строится с точностью до секунды (начало округляется вниз, длительность вверх, минимум 1 с), а в аудит попадают точные запрошенные миллисекунды. Готовый файл поэтому покрывает запрошенный интервал с запасом; нода дополнительно выравнивает его по опорным кадрам.
• Проверка интервала выполняется до проверки прав и записи аудита, поэтому отклонённый по диапазону запрос записи в аудите не оставляет. В аудит попадает только разрешённая выгрузка.

Ссылки общего доступа#

Ссылка — это выпущенный Plane токен, который нода принимает как параметр ?token= при запросе медиа. Ссылка привязана к одной камере, ограниченному набору бит привилегий, необязательному списку разрешённых сайтов-источников и сетей, списку протоколов и сроку действия. Это только медиа-доступ: административный API по ней не работает, PTZ — тоже.

POST /api/v1/cameras/{id}/shares#

Администратор

Назначение — выпустить отзываемую ссылку на одну камеру. Токен возвращается ровно один раз.

Параметры пути — id (uuid) — камера.

Тело запроса

unlimited и ttl_secs взаимоисключающи: допустимо либо unlimited: true без ttl_secs, либо unlimited: false с ttl_secs. Любая другая комбинация — 400 bad_ttl.

Пример curl — суточная ссылка на живой просмотр и превью (биты 1 + 32 = 33):

curl -sS -X POST "$BASE/api/v1/cameras/<UUID>/shares" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Подрядчик, монтаж",
    "bits": 33,
    "ttl_secs": 86400,
    "allowed_protocols": ["hls"],
    "allowed_referers": ["cctv.example.com"]
  }'

Пример ответа — 201 Created:

{
  "id": "<UUID>",
  "camera_id": "<UUID>",
  "name": "Подрядчик, монтаж",
  "bits": 33,
  "allowed_referers": ["cctv.example.com"],
  "allowed_protocols": ["hls"],
  "allowed_networks": [],
  "expires_at": "2026-08-19T10:00:00Z",
  "created_by": "<UUID>",
  "created_by_name": "Администратор",
  "created_at": "2026-08-18T10:00:00Z",
  "token": "eyJhbGciOi…",
  "live_url": "https://cctv.example.com/player/live/<UUID>?token=eyJhbGciOi…"
}

expires_at равен null у бессрочной ссылки. live_url и dvr_url вообще отсутствуют в ответе, если соответствующий бит не выдан или в списке протоколов нет ни одного браузерного (hls, mse).

Ошибки

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

Администратор

Назначение — список действующих ссылок камеры (отозванные и просроченные не показываются).

Параметры пути — id (uuid).

Пример curl

curl -sS "$BASE/api/v1/cameras/<UUID>/shares" -H "Authorization: Bearer $TOKEN"

Пример ответа

{
  "shares": [
    { "id": "<UUID>", "camera_id": "<UUID>", "name": "Подрядчик, монтаж",
      "bits": 33, "allowed_referers": ["cctv.example.com"],
      "allowed_protocols": ["hls"], "allowed_networks": [],
      "expires_at": "2026-08-19T10:00:00Z",
      "created_by": "<UUID>", "created_by_name": "Администратор",
      "created_at": "2026-08-18T10:00:00Z" }
  ]
}

Ошибки

Примечания — тот же набор полей, что при создании, без token, live_url и dvr_url. Сортировка — от новых к старым. Пагинации нет. created_by_name равен null, если выпустивший ссылку пользователь уже удалён.

DELETE /api/v1/shares/{id}#

Администратор

Назначение — немедленно отозвать ссылку.

Параметры пути — id (uuid) — идентификатор ссылки (не камеры).

Пример curl

curl -sS -X DELETE "$BASE/api/v1/shares/<UUID>" -H "Authorization: Bearer $TOKEN"

Пример ответа

{ "ok": true }

Ошибки

ONVIF#

POST /api/v1/onvif/discover#

Администратор

Назначение — однократный поиск ONVIF-устройств в локальной сети и список тех, кто ответил, с пометкой, какие из них уже заведены как камеры.

Тело запроса — не требуется (передавайте пустое тело; параметры поиска встроенные).

Пример curl

curl -sS -X POST "$BASE/api/v1/onvif/discover" -H "Authorization: Bearer $TOKEN"

Пример ответа

{
  "devices": [
    {
      "uuid": "urn:uuid:…",
      "xaddrs": ["http://192.0.2.10/onvif/device_service"],
      "scopes": ["onvif://www.onvif.org/name/Cam1"],
      "host": "192.0.2.10", "port": 80,
      "name": "Cam1", "hardware": "…",
      "known": false
    }
  ]
}

known: true означает, что камера с таким адресом уже есть в доступных вызывающему организациях.

Ошибки

Примечания — поиск ограничен по времени и по числу устройств, поэтому «болтливый» ответчик не переполнит выдачу. Ищутся только устройства в той же сети, что и Plane: за маршрутизатором многоадресный запрос не проходит — такие камеры заводите вручную или через туннель.

POST /api/v1/onvif/inspect#

Администратор

Назначение — опросить ещё не заведённое устройство с указанными в форме учётными данными, чтобы разметить профили до создания камеры.

Тело запроса

Пример curl

curl -sS -X POST "$BASE/api/v1/onvif/inspect" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"host":"192.0.2.10","port":80,"username":"operator","password":"ПАРОЛЬ-КАМЕРЫ"}'

Пример ответа

{
  "profiles": [
    { "token": "Profile_1", "name": "MainStream",
      "width": 1920, "height": 1080, "codec": "H264", "fps": 25.0,
      "stream_uri": "rtsp://192.0.2.10:554/…" }
  ],
  "device": { "manufacturer": "…", "model": "…", "firmware_version": "…",
              "serial_number": "…", "hardware_id": "…" }
}

stream_uri равен null, если устройство не отдало адрес потока.

Ошибки

Примечания

• Переданные учётные данные используются для одного запроса и не сохраняются и не пишутся в журналы. Возвращённые stream_uri — «голые» адреса без учётных данных; подстановка происходит уже после сохранения камеры.
• У этого маршрута нет привязки к организации и нет списка разрешённых адресов. Любой администратор организации может заставить Plane обратиться к любому хосту, до которого Plane дотягивается по сети. Это административная возможность, а не безопасный для арендаторов справочник — учитывайте это, раздавая роль администратора организации.

GET /api/v1/cameras/{id}/onvif/profiles#

Администратор

Назначение — получить с сохранённой камеры её текущий список профилей ONVIF, используя сохранённые учётные данные. Ничего не записывает.

Параметры пути — id (uuid).

Пример curl

curl -sS "$BASE/api/v1/cameras/<UUID>/onvif/profiles" -H "Authorization: Bearer $TOKEN"

Пример ответа

{ "profiles": [ { "token": "Profile_1", "name": "MainStream",
                  "width": 1920, "height": 1080, "codec": "H264", "fps": 25.0 } ] }

Ошибки

Примечания — пароль камеры читается внутри Plane для авторизации запроса к устройству, но клиенту не отдаётся и записью «просмотр пароля» в аудите не считается.

POST /api/v1/cameras/{id}/onvif/resolve#

Администратор

Назначение — опросить камеру и записать результат в её профили: назначить токены ONVIF там, где их не было (самое высокое разрешение — в main, самое низкое — в sub), и сохранить адреса потоков. После этого конфигурация применяется на ноде.

Параметры пути — id (uuid).

Тело запроса — не требуется.

Пример curl

curl -sS -X POST "$BASE/api/v1/cameras/<UUID>/onvif/resolve" -H "Authorization: Bearer $TOKEN"

Пример ответа — обновлённая камера в той же структуре, что и при создании; у профилей ONVIF теперь заполнен onvif_stream_uri.

Ошибки

Примечания — операция пишется в аудит; при неуспешной авторизации на устройстве дополнительно создаётся служебное событие об ошибке авторизации камеры. Пока разрешение адресов не выполнено, профиль onvif не стримит — заведение ONVIF-камеры без этого шага незаметно оставляет её без видео.

Отказ со стороны камеры: 502 onvif_upstream#

Любой маршрут ONVIF и PTZ может завершиться неудачей не на стороне Plane, а на стороне устройства. Такой случай — это 502 с расширенным телом:

{
  "error": "onvif_upstream",
  "detail": "camera_auth_failed",
  "kind": "…",
  "retry_after_seconds": 30
}

Текст ошибки от устройства наружу намеренно не передаётся. retry_after_seconds равен null, если подсказки о задержке нет; когда значение есть — блокируйте кнопку повтора ровно на этот срок, иначе попытки будут продлевать блокировку устройства.

PTZ#

POST /api/v1/cameras/{id}/ptz#

Любой вошедший — плюс право PTZ на эту камеру: камера должна заявлять ptz_pan_tilt или ptz_zoom; администратору достаточно прав на организацию камеры; оператору нужен бит PTZ на метке, которую камера несёт (её организация или один из её тегов). Операция set_preset дополнительно требует роли администратора.

Назначение — управление камерой: непрерывное движение, остановка, переход к предустановке, создание предустановки.

Параметры пути — id (uuid).

Тело запроса — вид операции задаёт поле op:

Пример curl — плавный поворот вправо, затем остановка:

curl -sS -X POST "$BASE/api/v1/cameras/<UUID>/ptz" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"op":"move","pan":0.4}'

curl -sS -X POST "$BASE/api/v1/cameras/<UUID>/ptz" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"op":"stop"}'

Пример ответа

{ "ok": true }

Для set_preset дополнительно возвращается токен, который назначила камера:

{ "ok": true, "token": "Preset_3" }

Ошибки

Примечания

• Команда move взводит сторожевой таймер на 2 секунды. Если новых команд не приходит, Plane сам отправляет камере Stop (до трёх попыток). Новая move отменяет отложенную остановку. Клиент, ведущий камеру джойстиком, обязан повторять move чаще, чем раз в 2 секунды; отпускание джойстика лучше подтверждать явной stop, а не полагаться на таймер.
• Записи аудита по PTZ схлопываются: подряд идущие действия одного пользователя по одной камере с промежутком менее 30 секунд превращаются в одну запись.
• Возможности PTZ берутся из полей камеры и записываются с учётом use_onvif, поэтому камера, сохранённая без ONVIF, не может стать PTZ-управляемой, что бы ни стояло в её флагах.

GET /api/v1/cameras/{id}/ptz/presets#

Любой вошедший — те же права PTZ, что и у команды управления; дополнительной проверки на администратора нет.

Назначение — список предустановок камеры. Кэша на стороне Plane нет: список запрашивается у самой камеры.

Параметры пути — id (uuid).

Пример curl

curl -sS "$BASE/api/v1/cameras/<UUID>/ptz/presets" -H "Authorization: Bearer $TOKEN"

Пример ответа

{ "presets": [ { "token": "Preset_1", "name": "Вход" },
               { "token": "Preset_2", "name": null } ] }

Ошибки — те же, что у команды управления, кроме ошибок конкретных операций: 404 not_found, 403 forbidden, 400 not_onvif, 400 ptz_not_supported, 400 no_host, 400 ptz_not_resolved, 502 onvif_upstream, 503 db_unavailable.

Примечания — name равен null, если камера имени не сообщает. Токены непрозрачны: не считайте их числами и не полагайтесь на их порядок — передавайте обратно ровно то, что получили, в поле preset операции goto_preset.

Телеметрия и статус в реальном времени#

GET /api/v1/cameras/{id}/telemetry/history#

Администратор

Назначение — временной ряд метрик одного профиля камеры (графики на карточке камеры). Plane определяет размещение и обращается к ноде сам; адрес и учётные данные ноды до браузера не доходят.

Параметры пути — id (uuid) — камера.

Параметры запроса

Пример curl

curl -sS "$BASE/api/v1/cameras/<UUID>/telemetry/history?profile=main&range=1h" \
  -H "Authorization: Bearer $TOKEN"

Пример ответа

{
  "id": "cam/<UUID>/main", "core": 3, "started_ms": 1755000000000,
  "range": "1m", "cadence_s": 1, "cap": 60,
  "samples": [
    { "ts": 1755000000, "bitrate": 2048, "fps": 25.0, "viewers": 3, "packets_in_per_s": 500 }
  ]
}

Ошибки

GET /api/v1/cameras/runtime/stream#

Администратор — операторы пользуются мобильным вариантом этого потока.

Назначение — поток SSE с состоянием набора камер в реальном времени. Авторизация и определение размещения выполняются один раз при подписке; все подписчики затем обслуживаются одним общим опросом нод.

Параметры запроса

Пример curl

curl -N -sS "$BASE/api/v1/cameras/runtime/stream?ids=<UUID>,<UUID>" \
  -H "Authorization: Bearer $TOKEN" -H 'Accept: text/event-stream'

Пример ответа — text/event-stream; кадры без имени события, с id: <номер> и комментарием поддержания соединения каждые 15 секунд:

id: 42
data: {"seq":42,"sampled_at":"2026-08-18T10:00:00Z","rows":{"<UUID>":{"alive":true,"profiles":2,"observed_profiles":2,"bitrate":2048.0,"fps":25.0,"packets_in_per_s":500.0,"codecs":["h264"],"errors":[],"health":"ok","profile_states":{"main":{"kind":"main","enabled":true,"observed":true,"alive":true,"on_demand":false,"bitrate":2048.0,"fps":25.0,"codecs":["h264"],"errors":[],"health":"ok","source_connected_ms":1755000000000,"reconnects":0}}}},"profiles":{}}

Поле profiles заполняется только при detail=true, иначе это пустой объект.

Ошибки

Примечания

• Неизвестные и недоступные идентификаторы молча выбрасываются из подписки, если разрешился хотя бы один: поток тогда охватывает меньше камер, чем вы просили. Сверяйте состав rows с тем, что запрашивали.
• Слот подписки удерживается всё время, пока открыто тело ответа: клиент, который открыл поток и не читает его, продолжает занимать слот. Закрывайте соединение явно.
• Поток завершается, когда истекает актуальность авторизации (не более 5 минут). Долгоживущая страница обязана переподключаться. Общие правила разбора кадров — в разделе Введение.

Шаблоны камер#

Шаблон камеры — это сохранённый набор настроек, который подставляется при создании камеры (профили, параметры архива, размещение). Полное описание маршрутов /api/v1/camera-templates — на странице Теги, мозаики, шаблоны: там же объясняется, чем шаблон камеры отличается от шаблона события.