Быстрый старт

От нуля до живого подписчика примерно за пять минут. Вы создадите поток, опубликуете в него пакет, подпишетесь и увидите, как он приходит, затем отключитесь и возобновите с курсора, ничего не потеряв.

Получите API-ключ

Каждому запросу, кроме эндпоинтов health и version, нужен ключ в заголовке Authorization. Для этого прохождения можно использовать публичный демо-ключ (только для чтения и с ограничением частоты) либо ваш собственный ключ из панели управления, когда у вас появится аккаунт.

# ваш собственный ключ из панели управления
export RUNNEV_API_KEY="rnv_live_00112233445566778899aabbccddeeff"

# проверка связи — авторизация не нужна
curl https://runnev.dev/v1/health
# {"status":"ok","uptime_s":1843302}

1. Создайте поток

Потоки идентифицируются по base62-идентификатору. Пусть сервер назначит его сам:

curl https://runnev.dev/v1/streams \
  -H "Authorization: Bearer $RUNNEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"quickstart","retention_seconds":3600}'

{
  "id": "RqrkHXc9bOQs9VlDT836jx",
  "name": "quickstart",
  "created_at": "2026-08-04T11:00:00Z",
  "retention_seconds": 3600,
  "max_bytes": 268435456,
  "cursor": 0,
  "bytes_stored": 0,
  "mode": "json"
}

Сохраните этот id; его использует любой другой вызов. Экспортируйте его для удобства:

export STREAM="RqrkHXc9bOQs9VlDT836jx"

2. Опубликуйте пакет

Основной путь записи помещает номер в URL. Начните с 1. Именно то, что номер выбираете вы сами, делает публикации идемпотентными — подробно об этом на странице Публикация.

curl https://runnev.dev/v1/streams/$STREAM/1 \
  -H "Authorization: Bearer $RUNNEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"type":"hello","msg":"first batch"}]}'

{"stream_id":"RqrkHXc9bOQs9VlDT836jx","seq":1,"accepted":1,"cursor":1,"duplicate":false}

3. Подпишитесь

Откройте второй терминал и держите подписку открытой. Флаг -N говорит curl не буферизовать, поэтому вы видите пакеты по мере поступления. По умолчанию подписка начинается с головы, так что опубликуйте снова из первого терминала и посмотрите, как это появится.

curl -N "https://runnev.dev/v1/streams/$STREAM?cursor=0" \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $RUNNEV_API_KEY"

: runnev

id: 1
event: batch
data: {"seq":1,"ts":"2026-08-04T11:00:12.418Z","events":[{"type":"hello","msg":"first batch"}]}

: keepalive

Строка, начинающаяся с двоеточия, — это кадр-комментарий. Runnev отправляет такой каждые 15 секунд, когда поток простаивает, чтобы посредники и клиенты могли отличить здоровое тихое соединение от мёртвого.

4. Возобновите с курсора

Остановите подписчика по Ctrl-C. Опубликуйте ещё пару пакетов, пока он отключён:

curl https://runnev.dev/v1/streams/$STREAM/2 \
  -H "Authorization: Bearer $RUNNEV_API_KEY" \
  -d '{"events":[{"type":"tick","n":2}]}'
curl https://runnev.dev/v1/streams/$STREAM/3 \
  -H "Authorization: Bearer $RUNNEV_API_KEY" \
  -d '{"events":[{"type":"tick","n":3}]}'

Теперь переподключитесь, начав после номера 1. Вы сразу получите 2 и 3, а затем — вживую:

curl -N "https://runnev.dev/v1/streams/$STREAM?cursor=1" \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $RUNNEV_API_KEY"

Это весь цикл: публикуете под номером, читаете с курсора, возобновляете с курсора после любого разрыва. SDK делают переподключение за вас.

То же самое с SDK

import { Runnev } from "@runnev/client";

const runnev = new Runnev({ apiKey: process.env.RUNNEV_API_KEY });

const stream = await runnev.createStream({ name: "quickstart", retentionSeconds: 3600 });
await runnev.publish(stream.id, 1, [{ type: "hello", msg: "first batch" }]);

for await (const batch of runnev.subscribe(stream.id, { cursor: 0 })) {
  console.log(batch.seq, batch.events);
}

import os
from runnev import Runnev

runnev = Runnev(api_key=os.environ["RUNNEV_API_KEY"])

stream = runnev.create_stream(name="quickstart", retention_seconds=3600)
runnev.publish(stream.id, 1, [{"type": "hello", "msg": "first batch"}])

for batch in runnev.subscribe(stream.id, cursor=0):
    print(batch.seq, batch.events)

Дальнейшие шаги

• Аутентификация — форматы ключей и режимы отказа.
• Публикация — номера, идемпотентность, режим raw, группировка в пакеты.
• Подписка — формат передачи SSE и долгоживущие соединения.