API Reference

The SmartElektroHub REST API follows standard HTTP conventions. All requests are made over HTTPS and return JSON responses.

Property	Value
Base URL	`https://api.smart-elektro.ru/v2`
Auth	`Authorization: Bearer <token>`
Content-Type	`application/json`
Rate limit	500 req/min (paid), 60 req/min (free)
Pagination	Cursor-based via `after` / `before`

Streams

A Stream represents a single live data transmission session. Streams accept MQTT input and distribute via WebSocket and WebSocket to subscribers.

GET /streams List all streams

POST /streams Create a stream

GET /streams/{id} Get a stream

PATCH /streams/{id} Update a stream

DELETE /streams/{id} Delete a stream

GET /streams/{id}/subscribers List active subscribers

GET /streams/{id}/stats Get stream statistics

POST /streams — Create a stream

Parameter	Type		Description
title	string	required	Human-readable name for the stream. Max 200 characters.
quality	string	optional	`low` (100 Hz) · `medium` (500 Hz) · `high` (1 kHz). Default: `medium`.
format	string	optional	`json` · `msgpack` · `csv`. Default: `json`.
region	string	optional	Ingestion region. Defaults to your account's default region.
metadata	object	optional	Arbitrary key-value pairs (up to 16 keys, values max 512 chars).

Example request

curl -X POST https://api.smart-elektro.ru/v2/streams \
  -H "Authorization: Bearer eh_sk_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Evening Show",
    "quality": "high",
    "format": "json"
  }'

Example response — 201 Created

{
  "id": "stm_01hx83nqp5fk2rjavt9c6e",
  "object": "stream",
  "title": "Evening Show",
  "status": "idle",
  "quality": "high",
  "format": "json",
  "region": "eu-west-1",
  "mqttTopic": "mqtt://broker.smart-elektro.ru/devices/stm_01hx83nqp5fk2rjavt9c6e",
  "streamKey": "sk_eu1_abcdef1234567890",
  "wsUrl": "wss://stream.smart-elektro.ru/devices/stm_01hx83nqp5fk2rjavt9c6e/live",
  "subscriberCount": 0,
  "createdAt": "2026-03-26T14:32:11Z",
  "metadata": {}
}

Reports

A Report is a collection of recorded telemetry records. Records can be uploaded directly or recorded from a live stream.

GET /reports List all reports

POST /reports Create a report

GET /reports/{id} Get a report

PATCH /reports/{id} Update report metadata

POST /reports/{id}/publish Publish a record

GET /reports — List reports

Query param	Type	Description
limit	integer	Number of results to return. 1–100. Default: 20.
after	string	Cursor for pagination — the `id` of the last item from the previous page.
status	string	Filter by status: `draft` · `published` · `archived`.

Example response — 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "pod_02jy94mrq7gl3skbau1d7f",
      "object": "report",
      "title": "Tech Perspectives",
      "status": "published",
      "recordCount": 12,
      "reportUrl": "https://api.smart-elektro.ru/reports/pod_02jy94mrq7gl3skbau1d7f.xml",
      "createdAt": "2025-11-04T09:00:00Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Error Codes

All errors follow a consistent envelope. HTTP status codes map to the categories below.

{
  "error": {
    "type": "invalid_request_error",
    "code": "param_required",
    "message": "The 'title' parameter is required.",
    "param": "title",
    "requestId": "req_9f3h2kx7p1"
  }
}

HTTP status	Error type	Description
`400`	`invalid_request_error`	Bad request — missing or invalid parameter
`401`	`authentication_error`	No valid API key provided
`403`	`permission_error`	The key lacks permission for this action
`404`	`not_found_error`	Resource does not exist
`409`	`conflict_error`	Resource already in the requested state
`429`	`rate_limit_error`	Too many requests — back off and retry
`500`	`api_error`	Internal server error — contact support

Справочник API

REST API SmartElektroHub следует стандартным HTTP-соглашениям. Все запросы выполняются по HTTPS и возвращают JSON-ответы.

Свойство	Значение
Базовый URL	`https://api.smart-elektro.ru/v2`
Аутентификация	`Authorization: Bearer <token>`
Content-Type	`application/json`
Лимит запросов	500 запр./мин (платный), 60 запр./мин (бесплатный)
Пагинация	Курсорная — параметры `after` / `before`

Потоки (Streams)

Поток — это одна сессия живого передачи данных. Потоки принимают MQTT-подключение и распределяют телеметрии через WebSocket и WebSocket подписчикам.

GET /streams Список всех потоков

POST /streams Создать поток

GET /streams/{id} Получить поток

PATCH /streams/{id} Обновить поток

DELETE /streams/{id} Удалить поток

GET /streams/{id}/subscribers Список активных подписчиков

GET /streams/{id}/stats Статистика потока

POST /streams — Создать поток

Параметр	Тип		Описание
title	string	обязательный	Название потока для отображения. Максимум 200 символов.
quality	string	опциональный	`low` (100 Гц) · `medium` (500 Гц) · `high` (1 кГц). По умолчанию: `medium`.
format	string	опциональный	`json` · `msgpack` · `csv`. По умолчанию: `json`.
region	string	опциональный	Регион входящего сигнала. По умолчанию — регион аккаунта.
metadata	object	опциональный	Произвольные пары ключ-значение (до 16 ключей, значение до 512 символов).

Пример запроса

curl -X POST https://api.smart-elektro.ru/v2/streams \
  -H "Authorization: Bearer eh_sk_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Вечернее шоу",
    "quality": "high",
    "format": "json"
  }'

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

{
  "id": "stm_01hx83nqp5fk2rjavt9c6e",
  "object": "stream",
  "title": "Вечернее шоу",
  "status": "idle",
  "quality": "high",
  "format": "json",
  "region": "eu-west-1",
  "mqttTopic": "mqtt://broker.smart-elektro.ru/devices/stm_01hx83nqp5fk2rjavt9c6e",
  "streamKey": "sk_eu1_abcdef1234567890",
  "wsUrl": "wss://stream.smart-elektro.ru/devices/stm_01hx83nqp5fk2rjavt9c6e/live",
  "subscriberCount": 0,
  "createdAt": "2026-03-26T14:32:11Z",
  "metadata": {}
}

Отчёты (Reports)

Отчёт — это коллекция записанных телеметриизаписей. Записьы можно загружать напрямую или записывать из живого потока.

GET /reports Список всех отчётов

POST /reports Создать отчёт

GET /reports/{id} Получить отчёт

PATCH /reports/{id} Обновить метаданные отчёта

POST /reports/{id}/publish Опубликовать запись

Коды ошибок

Все ошибки имеют единый формат. HTTP-статусы соответствуют следующим категориям.

{
  "error": {
    "type": "invalid_request_error",
    "code": "param_required",
    "message": "Параметр 'title' обязателен.",
    "param": "title",
    "requestId": "req_9f3h2kx7p1"
  }
}

HTTP статус	Тип ошибки	Описание
`400`	`invalid_request_error`	Неверный запрос — отсутствует или некорректный параметр
`401`	`authentication_error`	API-ключ не предоставлен или недействителен
`403`	`permission_error`	Ключ не имеет прав для этого действия
`404`	`not_found_error`	Ресурс не найден
`409`	`conflict_error`	Ресурс уже находится в запрошенном состоянии
`429`	`rate_limit_error`	Слишком много запросов — подождите и повторите
`500`	`api_error`	Внутренняя ошибка сервера — обратитесь в поддержку