Table of Contents

JSON API

The MultiProtoServer sample enables a built-in REST API for remote management of publishing points, sinks, and server monitoring. The API uses JSON request and response bodies and is served over the same HTTP server used by HLS, MPEG-DASH, and other HTTP-based protocols.

For the full endpoint reference with request/response schemas, see the Swagger API documentation.

Enabling the API

server.EnableJsonApi = true;
server.ApiServerParameters.Users.Add("admin", "admin");

The EnableJsonApi property activates the API server. At least one authentication method must be configured — either user credentials or a shared secret key.

This requires the VAST_FEATURE_API compilation symbol.

Authentication

The API supports two authentication mechanisms. All endpoints except /api/v1/ip and /api/v1/auth require a valid token passed in the request body.

Session-Based Authentication

Clients authenticate via POST /v1/auth with a username and password and receive a session token:

// Request
{
  "name": "admin",
  "password": "admin"
}

// Response
{
  "result": "OK",
  "token": "550e8400-e29b-41d4-a716-446655440000"
}

Session tokens expire after a period of inactivity. The token is passed in subsequent requests:

{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  ...
}

To revoke a session, call DELETE /v1/auth:

{
  "token": "550e8400-e29b-41d4-a716-446655440000"
}

Shared Key Token Authentication

For server-to-server communication without a login step, configure a shared secret key:

server.ApiServerParameters.SharedSecretKey = "your-secret-key";

Clients generate tokens locally using SHA-512 hashing. Token format: sk1-{timestamp}-{hash}. Default expiration is 60 seconds, configurable via SharedTokenExpiration.

ApiServerParameters

Property Default Description
Users empty Authorized username-password pairs for session-based authentication
SharedSecretKey null Shared secret for token-based authentication
SharedTokenExpiration null Token expiration duration (default: 60 seconds)
IsOnlineMode true Online mode flag affecting shared key token validation

API Endpoints

All responses include a result field set to "OK" on success or an error description on failure.

Publishing Points

Method Endpoint Description
POST /api/v1/publishing-point Create a new publishing point
GET /api/v1/publishing-point/{id-or-path} Get publishing point details by ID or path
PUT /api/v1/publishing-point/{id-or-path} Update an existing publishing point
DELETE /api/v1/publishing-point/{id-or-path} Stop and remove a publishing point

Creating a Mixing Publishing Point

The following example creates a mixing publishing point that composites multiple sources with a background image, auto-layout for live streams, and a watermark overlay:

// POST /v1/publishing-point?token=...
{
  "path": "mix",
  "title": "Mixing Publishing Point Test",
  "streaming-mode": "live",
  "allow-video-processing": true,
  "sources": [
    { "uri": "vast://publishing-point/host1" },
    { "uri": "vast://publishing-point/host2" },
    { "uri": "vast://publishing-point/host3" },
    { "uri": "vast://publishing-point/host4" },
    { "uri": "file:///api-background.jpg" },
    { "uri": "file:///api-watermark.png" },
    { "uri": "file:///api-audio-only.png" }
  ],
  "processing": {
    "video": {
      "discard": false,
      "transcoding": true,
      "tracks": [
        {
          "index": 0,
          "width": 1280,
          "height": 720,
          "framerate": "30/1",
          "keyframe-interval": 30,
          "bitrate": 3000000,
          "codec": "H264",
          "profile": 66,
          "mixing": {
            "type": "all",
            "layers": [
              {
                "sources": [ 4 ],
                "layout": "manual",
                "stretch": "fill"
              },
              {
                "sources": [ 0, 1, 2, 3 ],
                "layout": "auto",
                "stretch": "zoom"
              },
              {
                "sources": [ 5 ],
                "layout": "manual",
                "stretch": "fill",
                "location": [ 50, 50, 295, 109 ],
                "opacity": 0.7
              }
            ],
            "audio-source-image": 6
          }
        }
      ]
    },
    "audio": {
      "discard": false,
      "transcoding": true,
      "tracks": [
        {
          "index": 1,
          "sample-rate": 44100,
          "channels": 1,
          "bitrate": 128000,
          "codec": "AAC",
          "mixing": {
            "type": "all"
          }
        }
      ]
    }
  }
}

Key request properties:

Property Type Description
path string Publishing point path
title string Human-readable title
streaming-mode string "live" or "vod"
allowed-protocols string Comma-separated list: hls, dash, rtsp, rtmp, srt, webrtc
sources array Input sources (URI or publishing point reference)
processing object Video/audio transcoding and mixing configuration

Source URIs explained:

  • vast://publishing-point/<path> — references another publishing point on the same server. When somebody starts publishing to e.g. rtmp://server/live/host1, the mixing publishing point picks up the stream automatically.
  • file:///<filename> — path relative to the server binary folder. Absolute file URIs (e.g. file:///C:/Images/image.png) and HTTP URLs can also be used.

Video layers are declared with incrementing Z order — each subsequent layer overlaps all previous layers:

Layer Sources Layout Description
0 Background image (source 4) manual, fill Full-frame background
1 Live streams (sources 0–3) auto, zoom Auto-arranged grid of connected publishers
2 Watermark (source 5) manual, fill Semi-transparent overlay at position [50, 50, 295, 109]

The audio-source-image property specifies which image to display when a source provides audio only (no video).

A layer with manual layout must reference exactly one source. A layer with auto layout can reference any number of sources.

Updating Mixing Settings

Use PUT to update processing settings without recreating the publishing point:

// PUT /v1/publishing-point/mix?token=...
{
  "processing": {
    "video": {
      "tracks": [
        {
          "index": 0,
          "mixing": {
            "type": "all",
            "layers": [
              {
                "sources": [ 4 ],
                "layout": "manual",
                "stretch": "fill"
              },
              {
                "sources": [ 0 ],
                "layout": "manual",
                "stretch": "zoom"
              },
              {
                "sources": [ 5 ],
                "layout": "manual",
                "stretch": "fill",
                "location": [ 50, 50, 295, 109 ],
                "opacity": 0.7
              }
            ],
            "audio-source-image": 6
          }
        }
      ]
    }
  }
}

This example changes layer 1 from an auto-layout grid of all connected sources to a full-screen view of source 0 only.

Updating Sources

When the source list changes, the complete new list must be provided. If the updated source list affects source indices used in mixing settings, updated mixing settings must be included in the same request:

// PUT /v1/publishing-point/mix?token=...
{
  "sources": [
    { "uri": "vast://publishing-point/host1" },
    { "uri": "vast://publishing-point/host2" },
    { "uri": "vast://publishing-point/host3" },
    { "uri": "vast://publishing-point/host4" },
    { "uri": "vast://publishing-point/host5" },
    { "uri": "vast://publishing-point/host6" },
    { "uri": "file:///api-background.jpg" },
    { "uri": "file:///api-watermark.png" },
    { "uri": "file:///api-audio-only.png" }
  ],
  "processing": {
    "video": {
      "tracks": [
        {
          "index": 0,
          "mixing": {
            "type": "all",
            "layers": [
              {
                "sources": [ 6 ],
                "layout": "manual",
                "stretch": "fill"
              },
              {
                "sources": [ 0, 1, 2, 3, 4, 5 ],
                "layout": "auto",
                "stretch": "zoom"
              },
              {
                "sources": [ 7 ],
                "layout": "manual",
                "stretch": "fill",
                "location": [ 50, 50, 295, 109 ],
                "opacity": 0.7
              }
            ],
            "audio-source-image": 8
          }
        }
      ]
    }
  }
}

This example adds two more publisher sources (host5, host6), which shifts the background, watermark, and audio-only image indices from 4/5/6 to 6/7/8. The mixing settings are updated accordingly.

Deleting a Publishing Point

DELETE /v1/publishing-point/mix?token=...

Sinks

Method Endpoint Description
POST /api/v1/sink?token=... Add a sink to an existing publishing point
DELETE /api/v1/sink/{sink-id}?token=... Remove a sink

Adding a Sink

// POST /v1/sink?token=...
{
  "path": "stream1",
  "sink": {
    "uri": "file:///recordings/backup.mp4",
    "format": "mediafile"
  }
}

Either path or publishing-point-id must be specified to identify the target publishing point.

Monitoring

Method Endpoint Description
GET /api/v1/ip Get the client's IP address (no authentication required)
GET /api/v1/stat?token=... Get server statistics
GET /api/v1/test-speed?token=... Download speed test
POST /api/v1/test-speed?token=... Upload speed test

Server Statistics

// GET /v1/stat
// Response
{
  "result": "OK",
  "stat": {
    "connection-count": 42,
    "publishing-point-count": 5,
    "cpu-usage": 45.3,
    "memory-usage": 62.1,
    "gpu-3d-usage": 0.0,
    "gpu-decoder-usage": 0.0,
    "gpu-encoder-usage": 35.5
  }
}

Programmatic Access

The same API model types used by the REST API can be used directly in code. For example, the Mixing Source uses ApiPublishingPointRequest to configure its pipeline via MixingSource.Update().

See Also