Is the Nx Cloud up? Visit our Status Page for the current health and performance of the Nx Cloud.

Status Page

Update RTSP stream URLs using the REST API

Nx Support
Updated

This guide shows you how to programmatically retrieve and update attributes for a generic RTSP resource using the REST API. You can perform these steps manually with an API testing client or automate them using a script.

Before making updates, ensure you have obtained a session token to authenticate your requests.

Retrieve current RTSP resource attributes

To update a resource, you must first identify its ID and check its current stream configuration. Query your Server to list all manually added Generic RTSP streams along with their IDs and active URLs.

To get a list of your generic RTSP devices:

  1. Send a GET request to the /rest/v4/devices endpoint.

  2. Include the query parameters vendor=GENERIC_RTSP and _with=name,id,streamUrls to filter the results.

  3. Include your session token in the authorization header as a bearer token.

Request example

GET /rest/v4/devices?vendor=GENERIC_RTSP&_with=name,id,streamUrls HTTP/1.1
Host: localhost:7001
Authorization: Bearer <token>
Accept: application/json

Response example

The server returns an array of JSON objects containing the matching devices:

[
  {
    "id": "3a197fa3-64d7-ba3b-105b-4794254f5299",
    "name": "Generic RTSP Camera 1",
    "streamUrls": {
      "1": "rtsp://localhost:8554/mh",
      "2": ""
    }
  }
]

Note the id of the resource you want to modify.

Update RTSP resource stream URLs

Once you have the target resource ID, you can add or modify its stream URLs.

To update a device's stream configuration:

  1. Send a PATCH request to the /rest/v4/devices/{id} endpoint, replacing {id} with your device's ID.

  2. In the request body, pass a JSON object containing the streamUrls key with your updated stream mapping.

Request example

PATCH /rest/v4/devices/3a197fa3-64d7-ba3b-105b-4794254f5299 HTTP/1.1
Host: localhost:7001
Authorization: Bearer <token>
Content-Type: application/json

{
  "streamUrls": {
    "1": "rtsp://localhost:8554/mh",
    "2": "rtsp://localhost:8554/ml"
  }
}

This request adds a secondary low-resolution stream ("2") to the target device while maintaining or updating the primary stream ("1").

Automate updates with Python

You can automate this update process using the Python requests library. The following script updates the stream URLs for a specific device ID.

import requests

# Define your connection, credentials, and target resource details
server_url = "https://localhost:7001"
username = "admin"
password = "password123"
device_id = "3a197fa3-64d7-ba3b-105b-4794254f5299"

# 1. Authenticate to get a session token
login_url = f"{server_url}/rest/v4/login/sessions"
login_payload = {
    "username": username,
    "password": password,
    "setCookie": True,
    "durationS": 100,
    "setSession": True
}

print("Requesting authentication token...")
# Note: verify=False ignores self-signed SSL certificate warnings. 
# In production, use a trusted certificate and set verify=True.
login_response = requests.post(login_url, json=login_payload, verify=False)

if login_response.status_code != 200:
    print(f"Authentication failed. Status code: {login_response.status_code}")
    print(login_response.text)
    exit(1)

bearer_token = login_response.json().get("token")
print("Token successfully generated.")

# 2. Update the RTSP stream URLs using the token
headers = {
    "Authorization": f"Bearer {bearer_token}",
    "Content-Type": "application/json"
}

update_url = f"{server_url}/rest/v4/devices/{device_id}"
payload = {
    "streamUrls": {
        "1": "rtsp://localhost:8554/mh",
        "2": "rtsp://localhost:8554/ml"
    }
}

print("Updating stream URLs...")
response = requests.patch(
    update_url,
    headers=headers,
    json=payload,
    verify=False
)

# 3. Verify the response
if response.status_code == 200:
    print("Device streams updated successfully.")
    print(response.json())
else:
    print(f"Failed to update device. Status code: {response.status_code}")
    print(response.text)

Security and Authentication

Security Warning: Hardcoding credentials (such as usernames and passwords) directly inside your scripts is highly discouraged in production environments. If this script is shared, committed to a version control system (like GitHub), or accessed by unauthorized users, your system credentials will be exposed. For production deployments, always use a secure secrets manager or restrict access permissions on the script file.

Ensure you use an active session token to authenticate your REST API requests and scripts. For detailed instructions on how to obtain and manage your token, see the Authentication Support Article.

Related articles

Comments

0 comments

Article is closed for comments.