Docs menu

Open API

On this page

Addresses and formats
Authentication
Endpoints a view token can use
Devices
Live video
Security notes

Rerinku View provides an open HTTP API that web pages, server-side programs and apps can call directly. For web pages, we recommend the Web SDK, which handles authentication, signaling and reconnection for you. This page describes the API itself, for other languages or for writing your own client.

Addresses and formats

The base URL is Rerinku View’s address: a LAN address (such as http://192.168.1.10:8080), or the Quick Connect address when Quick Connect is on. The Settings → Developer page lists the addresses you can use. All endpoints are under /api/v1/.
Successful responses are always wrapped in data: { "data": ... }. Binary and media responses (JPEG, SDP) aren’t wrapped.
Error responses are always { "error": { "message": "...", "code": "..." } }. Handle them by HTTP status code. Errors you may need to tell apart (authentication, live stream signaling) carry a machine-readable code.
Request bodies don’t allow extra fields: sending even one extra field returns 400.
Times are always RFC 3339.

Authentication

Send the token in a request header:

Authorization: Bearer <token>

Token	How to get it	What it can do
Read-only view token	Generate it under Settings → Developer in the console. It can only be generated in the console	Can only call the few endpoints in the table below. It can go in a public web page
Full token	`POST /api/v1/auth/bind` (binds the same way as the mobile app)	Full permissions for that binding

Every token is listed under Settings → Developer → Authorized apps (GET /api/v1/clients), and can be revoked at any time (DELETE /api/v1/clients/{id}). After revocation, requests return 401 with code set to invalid_token.

Cross-origin rules

Any website can call the API across origins. There’s no access password to set and no origins to register (CORS allows every origin and doesn’t send Allow-Credentials). The one hard rule: requests from other websites must carry a token. Otherwise, any page a visitor opens could use their browser to operate the Rerinku View on your LAN.

Request from another website	Result
`GET /api/v1/auth/info`	Works as usual; no token needed
`POST /api/v1/auth/bind`	If Rerinku View has an access password: works as usual (bind checks the password). If not: `403` with `code` set to `cross_site_bind`
All other `/api/v1/*`	Works as usual with a valid token. Without one: `401` with `code` set to `authentication_required`

Server-side programs and native apps don’t send an Origin header, so this rule doesn’t apply to them. Whether they need a token depends on the address Rerinku View listens on: not when it listens on loopback only, yes when it listens on a LAN address (the default).

Binding for a full token

POST /api/v1/auth/bind
Content-Type: application/json

{ "password": "", "name": "Store dashboard", "platform": "sdk", "device_id": "dash-0001", "app_version": "1.0" }

{ "data": { "access_token": "<token>", "token_type": "Bearer" } }

password: Rerinku View’s access password. Pass an empty string if none is set.
device_id: an installation ID that you generate and keep long-term (8–64 letters, digits or -). Binding again with the same ID only replaces the token; it doesn’t add another authorization.
A wrong password returns 401 (invalid_password). Too many attempts return 429 (too_many_attempts).

Endpoints a view token can use

Endpoint	Description
`GET /api/v1/devices`	Device list. A view token gets redacted fields: no addresses, MAC, serial number, hardware ID, or recording and PTZ configuration
`GET /api/v1/devices/{id}/streams`	The device’s stream catalog
`GET /api/v1/devices/{id}/thumbnail`	Thumbnail of the latest frame (JPEG)
`GET /api/v1/devices/{id}/runtime`	The device’s current runtime status. Only devices connected with the Rerinku View SDK can answer
`POST /api/v1/devices/{id}/live`, `POST /api/v1/devices/{id}/streams/{stream}/live`	Pull live video (WebRTC)
`GET /api/v1/ice-servers`	STUN/TURN configuration for live video

Every other endpoint returns 403 to a view token, with code set to insufficient_scope. A full token can use more endpoints; see docs/API.md in the Rerinku View repository.

Devices

GET /api/v1/devices

{
  "data": [
    {
      "id": 3,
      "sn": "0123456789ABCDEF",
      "name": "Front Door",
      "protocol": "onvif",
      "group": "First floor",
      "online": true,
      "streaming": false,
      "stream_kind": "webrtc",
      "video_codec": "H265",
      "has_thumbnail": true,
      "streams": [
        {
          "id": "main",
          "name": "Main stream",
          "default": false,
          "tracks": [{ "kind": "video", "codec": "H265" }]
        },
        {
          "id": "sub",
          "name": "Sub-stream",
          "default": true,
          "tracks": [{ "kind": "video", "codec": "H264" }]
        }
      ]
    }
  ]
}

When stream_kind is unsupported, browsers can’t play this device’s video.
streams lists the device’s streams. The one with default: true plays when no stream is specified.
Devices connected with the Rerinku View SDK also carry ext: static information the device reports about itself (SoC, CPU, memory, sensor…).

GET /api/v1/devices/{id}/runtime returns the device’s current status:

{
  "data": {
    "supported": true,
    "online": true,
    "at": 1793000000000,
    "values": { "tempC": 63.6, "cpuPct": 11.2 }
  }
}

The platform asks the device live every time, and reuses the result for the same device within 2 seconds, so don’t poll faster than that.

Live video

Live video is a one-shot SDP exchange, the same approach as WHEP:

Call GET /api/v1/ice-servers for the STUN/TURN configuration, and create an RTCPeerConnection with it (TURN credentials expire, so fetch it before every connection).
Add receive-only (recvonly) video and audio transceivers, create an offer, and wait for ICE gathering to finish.
POST the offer as the request body and get the answer back:

POST /api/v1/devices/{id}/streams/{stream}/live
Content-Type: application/sdp
Authorization: Bearer <token>

<raw SDP offer>

On success, it returns 201 with Content-Type: application/sdp, and the body is the raw SDP answer. Without /streams/{stream}, the default stream plays.

Status code	Meaning	Advice
`404`	The device or stream doesn’t exist	Don’t retry
`409`	The device is offline (`code`: `device_offline`)	Retry slowly, for example every 15 seconds
`422`	Something is wrong with the offer, or this connection type doesn’t support choosing a stream	Don’t retry
`408`, `504`	Signaling timed out, or the device didn’t respond to the stream start	You can retry
`502`, `503`	The device side or the service is temporarily unavailable	Retry with backoff

After a disconnect, just do the exchange again at the same address. The Web SDK’s reconnection strategy follows this table.

Security notes

A public web page contains your Rerinku View’s address. A view token only restricts requests that carry it. If that Rerinku View has no access password, anyone who knows the address can open the console directly (a tool like curl can also fake a browser’s same-origin request), so the view token’s limits don’t stop them, and the Quick Connect address itself works like a key. For a Rerinku View that hosts a public demo, set an access password, or turn on demo mode (DEMO_MODE) so everyone can only look, not change anything. Also, with Quick Connect set up, /api/v1/ice-servers returns this node’s TURN credentials (valid for 24 hours). Made public, they could be taken and used to relay traffic.