Developer Reference v2.4

RelayCDN Ingest & Edge Delivery API

RelayCDN provides low-latency ingestion endpoints and multi-protocol edge delivery for broadcast-grade video streams, interactive WebRTC relays, and CMAF/HLS distributions.

Overview & Edge Architecture

All video ingestion traffic is handled through our high-speed edge clusters (e.g. video.relaycdn.me, eu-north.relaycdn.me, ru-east.relaycdn.me). Incoming frames are processed in memory using zero-copy ring buffers and forwarded immediately to our distributed edge cache layers without disk write overhead.

To achieve minimum latency, RelayCDN supports direct HTTP/2 stream multiplexing, WebSockets over TLS, and pure gRPC bidirectional byte streaming alongside standard REST endpoints.

Authentication & Headers

Every request to RelayCDN edge endpoints must include your API Bearer token in the Authorization header or via the X-Relay-Stream-Key custom header:

Header Specification

Authorization: Bearer rcdn_live_9a87f2e1c3a04ef98b1a
X-Relay-Stream-Key: rcdn_live_9a87f2e1c3a04ef98b1a
X-Relay-Channel: live_broadcast_01
X-Relay-Timestamp: 1771688301

Edge Domains & Anycast Routing

You can point your ingestion encoder to either our global Anycast hostname or region-pinned clusters:

Region / Cluster	Edge Hostname	Target Protocol
Global Anycast	`video.relaycdn.me`	HTTPS / WSS / gRPC
Nordic (FI/SE)	`fi-01.relaycdn.me`	HTTP/3 / gRPC Ingest
Western EU (FR/DE)	`fr-02.relaycdn.me`	HTTP/2 / LL-HLS Relay
Eastern EU (RU)	`ru-01.relaycdn.me`	Direct BGP Ingest / WS

Create Stream Session

POST https://video.relaycdn.me/v1/ingest/stream/live

Initializes a live streaming channel session and provisions dedicated edge ring buffer slots across target PoP nodes.

Request Parameters (JSON Body)

Parameter	Type	Description
`channel_id`	string	Unique stream channel identifier (e.g. `gaming_stream_01`).
`protocol`	string	Ingest transport mode: `ll_hls_grpc`, `websocket_raw`, or `cmaf_chunked`.
`transcode_profile`	string	ABR profile: `passthrough`, `1080p60_abr`, `720p60_abr`.
`preferred_region`	string	Edge deployment target: `anycast`, `eu-north-helsinki`, `eu-west-paris`, `ru-east-moscow`.

Example Request & Response

// 1. POST Ingestion Setup
curl -X POST https://video.relaycdn.me/v1/ingest/stream/live \
  -H "Authorization: Bearer rcdn_live_9a87f2e1c3" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "nordic_esports_main",
    "protocol": "ll_hls_grpc",
    "transcode_profile": "1080p60_abr"
  }'

// 2. Edge Response (201 Created)
{
  "status": "active",
  "stream_id": "str_89ef410ae2",
  "assigned_pop": "FI-01-HELSINKI",
  "ingest_endpoints": {
    "grpc": "grpc://video.relaycdn.me:443",
    "websocket": "wss://video.relaycdn.me/v1/realtime/tunnel?sid=str_89ef410ae2",
    "http_chunked": "https://video.relaycdn.me/v1/stream/ingest/str_89ef410ae2"
  },
  "playback_url": "https://video.relaycdn.me/v1/edge/playback/str_89ef410ae2.m3u8"
}

WebSocket Real-Time Stream Pipe

WS / WSS wss://video.relaycdn.me/v1/realtime/tunnel

Provides continuous, bi-directional binary frame streaming over a single long-lived TLS connection. Ideal for sub-second WebRTC fallback and real-time video chunk transmission.

Node.js WebSocket Streaming Client

import WebSocket from 'ws';

const ws = new WebSocket('wss://video.relaycdn.me/v1/realtime/tunnel', {
  headers: {
    'Authorization': 'Bearer rcdn_live_9a87f2e1c3',
    'X-Relay-Session-ID': 'str_89ef410ae2',
    'X-Relay-Transport-Type': 'video-raw-fmp4'
  }
});

ws.on('open', () => {
  console.log('[RelayCDN] Connected to Edge Ingest Gateway');
  // Continuously pipe binary video chunks
  videoReadStream.on('data', (chunk) => {
    ws.send(chunk);
  });
});

ws.on('message', (data) => {
  const ack = JSON.parse(data.toString());
  console.log(`[Ack] Frame seq #${ack.seq} committed at edge (${ack.pop})`);
});

gRPC Binary Multiplexer Service

gRPC relaycdn.v1.streaming.RelayIngestService/StreamChunkPipe

For ultra-high-density video pipelines with multi-gigabit throughput. Operates via HTTP/2 and HTTP/3 multiplexing with binary protobuf encoding.

Protobuf Service Definition

syntax = "proto3";
package relaycdn.v1.streaming;

service RelayIngestService {
  rpc StreamChunkPipe (stream VideoFrameChunk) returns (stream IngestAck);
}

message VideoFrameChunk {
  string stream_token  = 1;
  uint64 sequence_id   = 2;
  bytes  payload_data  = 3;
  int64  pts_timestamp = 4;
  string codec_profile = 5;
}

message IngestAck {
  uint64 sequence_id  = 1;
  uint32 latency_micros = 2;
  string edge_pop_id  = 3;
}

Edge Playback Delivery

GET https://video.relaycdn.me/v1/edge/playback/{stream_id}.m3u8

Delivers the Low-Latency HLS master playlist with byte-range partial segment manifests (#EXT-X-PART) to player clients worldwide.

Status & Response Codes

Code	Status	Description
`200 OK`	Success	Stream session active or manifest rendered successfully.
`201 Created`	Session Provisioned	New ingestion channel allocated on edge PoPs.
`401 Unauthorized`	Auth Failed	Missing or expired `Authorization` token.
`404 Not Found`	Unknown Stream	Stream ID not found or channel decommissioned.
`429 Rate Limit`	Bandwidth Exceeded	Ingestion bitrate exceeds configured tier threshold.
`503 Unavailable`	PoP Rebalancing	Edge node undergoing maintenance, reroute via Anycast.