Skip to main content

TECHNICAL GUIDE

NDI API Reference Guide

Hal Hope
  • Updated

Looking for visual interface instructions? See the NRS NDI Plugin User & Admin Guide.

This reference guide details the NDI API v7 RESTful endpoints available on Vizrt NRS storage systems. Version 7 features a re-architected API structure designed to align with the ShareBrowser API standard. All API responses return a top-level status attribute along with a data payload for informational queries.

API Architecture Overview

The NDI API uses standard HTTP methods (GET and POST) to manage authentication, query available NDI streams, set up recording paths, and trigger captures.

  • Base URL: http://[NRS-IP]
  • Response Format: JSON envelope containing:
    • status — Indicates execution result (e.g., "success", "pending", or failure status).
    • data — Returned dataset, object, array, or session token string.
  • Authentication: All protected endpoints require a valid session token passed via the ndi_token POST parameter.

Authentication Endpoints

1. User Login

Authenticates user credentials and returns a session token required for subsequent API operations.

Endpoint: /ndi/api/get_token
Method: POST

Parameters:

  • username — EVO / NRS account username.
  • password — Account password.

Sample cURL Request:

curl -X POST -d "username=sns" -d "password=sns" http://[NRS-IP]/ndi/api/get_token

Sample Response:

{
  "status": "success",
  "data": "gbplrkkaacgz",
  "role": "user"
}

2. User Logout

Invalidates an active NDI session token.

Endpoint: /ndi/api/logout
Method: POST

Parameters:

  • ndi_token — Active authentication token.

Sample cURL Request:

curl -d "ndi_token=gbplrkkaacgz" http://[NRS-IP]/ndi/api/logout

Sample Response:

{
  "status": "success"
}

System & Storage Endpoints

1. Get Available NDI Channels

Retrieves a list of all active NDI video streams currently discovered across the local network.

Endpoint: /ndi/api/get_channels
Method: GET

Parameters: None

Sample cURL Request:

curl http://[NRS-IP]/ndi/api/get_channels

Sample Response:

{
  "status": "success",
  "data": [
    "ELITE-AADE681E (5)",
    "ELITE-AADE681E (6)"
  ]
}

2. Get Accessible Shares

Returns all storage shares accessible to the authenticated user account.

Endpoint: /ndi/api/get_shares
Method: POST

Parameters:

  • ndi_token — Active authentication token.

Sample cURL Request:

curl -d "ndi_token=gbplrkkaacgz" http://[NRS-IP]/ndi/api/get_shares

Sample Response:

{
  "status": "success",
  "data": [
    "Capture",
    "Media"
  ]
}

3. Get Recording Locations

Retrieves all existing storage targets configured for NDI ingest.

Endpoint: /ndi/api/get_locations
Method: POST

Parameters:

  • ndi_token — Active authentication token.

Sample cURL Request:

curl -d "ndi_token=gbplrkkaacgz" http://[NRS-IP]/ndi/api/get_locations

Sample Response:

{
  "status": "success",
  "data": [
    {
      "location_name": "newlocation",
      "share": "Capture",
      "fullpath": "Capture/new folder"
    }
  ]
}

4. Set Recording Location

Creates or updates a designated recording target on an assigned storage share.

Endpoint: /ndi/api/set_location
Method: POST

Parameters:

  • ndi_token — Active authentication token.
  • loc_name — Descriptive name for the storage target.
  • share_name — Target mounted EVO/NRS share name.
  • share_path — Relative folder path on the specified share.

Sample cURL Request:

curl -d "ndi_token=gbplrkkaacgz&loc_name=newlocation&share_name=Capture&share_path=new%20folder" http://[NRS-IP]/ndi/api/set_location

Sample Response:

{
  "status": "success",
  "data": [
    {
      "location_name": "newlocation",
      "share": "Capture",
      "fullpath": "Capture/new folder"
    }
  ]
}

Recording Control Endpoints

1. Get Current Recordings

Returns details on all currently active NDI recording processes.

Endpoint: /ndi/api/get_recordings
Method: POST

Parameters:

  • ndi_token — Active authentication token.

Sample cURL Request:

curl -d "ndi_token=gbplrkkaacgz" http://[NRS-IP]/ndi/api/get_recordings

Sample Response:

{
  "status": "success",
  "data": [
    {
      "pid": "314",
      "out_path": "/root/app/users/sns/shares/Capture/new folder/2023-01-19_18-51-58/ELITE-AADE681E (MIX 1)",
      "channel_name": "ELITE-AADE681E (MIX 1)",
      "still_running": true,
      "frame_rate_n": "60000",
      "frame_rate_d": "1001",
      "xres": "3840",
      "yres": "2160",
      "start_timecode": "679195665574"
    }
  ]
}

2. Start Recording

Triggers a new NDI capture session for a specified NDI channel and target location.

Endpoint: /ndi/api/start_recording
Method: POST

Parameters:

  • ndi_token — Active authentication token.
  • channel — NDI stream channel name (from /ndi/api/get_channels).
  • location — Target storage location name (from /ndi/api/get_locations).

Sample cURL Request:

curl -d "ndi_token=gbplrkkaacgz&channel=channelName&location=locName" http://[NRS-IP]/ndi/api/start_recording

Sample Response:

{
  "status": "pending"
}

3. Stop Recording

Stops an active recording session by Process ID (PID).

Endpoint: /ndi/api/stop_recording
Method: POST

Parameters:

  • ndi_token — Active authentication token.
  • pid — Process ID of the active recording (from /ndi/api/get_recordings).

Sample cURL Request:

curl -d "ndi_token=gbplrkkaacgz&pid=456" http://[NRS-IP]/ndi/api/stop_recording

Sample Response:

{
  "status": "success",
  "data": "Stopped recording PIDs: 456"
}

Related Articles

  • NRS NDI Plugin User & Admin Guide — Complete user and administrative guide covering GUI navigation, share configuration, live preview behaviors, and playout workflows.

Related articles