Managing Instances ¶

An instance is a single configured pipeline: one input source, one solution (such as SecuRT), and its analytics and output settings. This tutorial walks through the full lifecycle of an instance using the RT Core API, from creation to deletion.

All endpoints here live under the /v1/core namespace. See the REST API overview for base URL, authentication, and conventions.

The instance lifecycle ¶

An instance moves through three states:

State	Meaning
Registered	The instance exists and has configuration, but consumes no runtime resources.
Loaded	The solution and models are loaded into memory. The pipeline is ready but not processing frames.
Running	The instance is actively reading its input and producing detections, events, and outputs.

The relevant transitions are:

load / unload - move between registered and loaded.
start / stop - move between loaded and running. start will load the instance automatically if needed.
restart - convenience for stop followed by start.

A persistent instance is saved to a JSON file in the instances folder and is restored when RT Server restarts. A non-persistent instance lives only in memory and disappears when the server stops.

There is no pause

The API exposes start, stop, load, unload, and restart. There is no separate "pause" operation — use stop to halt processing.

Listing instances ¶

Retrieve every registered instance:

curl -X GET "http://localhost:3546/v1/core/instances"

The response wraps the instances in an instances array:

{
  "instances": [
    {
      "instanceId": "2fa13902-7d9e-4e97-85e4-723f34d73f53",
      "displayName": "Front Entrance",
      "group": "building-a",
      "solutionId": "securt",
      "solutionName": "SecuRT (Security)",
      "persistent": true,
      "loaded": false,
      "running": false,
      "fps": 0.0,
      "version": "14.14.613fc04",
      "detectorMode": "SmartDetection",
      "detectionSensitivity": "Medium",
      "movementSensitivity": "Medium",
      "sensorModality": "RGB",
      "autoStart": false,
      "autoRestart": true,
      "readOnly": false
    }
  ]
}

Getting a single instance ¶

curl -X GET "http://localhost:3546/v1/core/instance/2fa13902-7d9e-4e97-85e4-723f34d73f53"

Returns the same object as above for one instance, or 404 Not Found if the ID is unknown.

Creating an instance ¶

POST /v1/core/instance registers a new instance and returns its generated UUID.

curl -X POST "http://localhost:3546/v1/core/instance" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Entrance",
    "group": "building-a",
    "solution": "securt",
    "persistent": true,
    "autoRestart": true
  }'

Response (201 Created):

{
  "instanceId": "899c89f9-90c3-c633-8586-8f09b005ebed"
}

Useful fields in the request body:

Field	Type	Description
`name`	string	Display name of the instance.
`group`	string	Optional group used to organize instances.
`solution`	string	Solution ID to bind, for example `securt`. List the available IDs with `GET /v1/core/solutions`.
`persistent`	boolean	Save the instance to disk so it survives a restart.
`frameRateLimit`	number	Maximum processing frame rate (`0` = unlimited).
`detectorMode`	enum	`SmartDetection` or `Detection`.
`detectionSensitivity`	enum	`Low`, `Medium`, or `High`.
`movementSensitivity`	enum	`Low`, `Medium`, or `High`.
`sensorModality`	enum	`RGB` or `Thermal`.
`autoStart`	boolean	Start the instance automatically when RT Server starts.
`autoRestart`	boolean	Restart the instance automatically if it stops unexpectedly.

List available solutions first

curl "http://localhost:3546/v1/core/solutions"

{
  "solutions": [
    { "id": "securt", "name": "SecuRT (Security)", "version": "14.14.613fc04" }
  ]
}

Creating an instance with a chosen ID ¶

If you need to assign the UUID yourself (for example to keep IDs consistent across machines), use PUT with the ID in the path:

curl -X PUT "http://localhost:3546/v1/core/instance/2fa13902-7d9e-4e97-85e4-723f34d73f53" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Entrance",
    "solution": "securt",
    "persistent": true
  }'

Returns 201 Created, or 409 Conflict if an instance with that ID already exists.

Setting the input source ¶

Point the instance at a video source with POST /v1/core/instance/{instanceId}/input:

curl -X POST "http://localhost:3546/v1/core/instance/899c89f9-90c3-c633-8586-8f09b005ebed/input" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "RTSP",
    "uri": "rtsp://user:[email protected]:554/stream1"
  }'

type - RTSP for network cameras, or Manual when frames are pushed in programmatically.
uri - the source URI. RTSP URLs may embed credentials as shown above.

Returns 204 No Content.

Controlling the lifecycle ¶

Each of the following is a POST that takes no parameters and returns 204 No Content on success. Each standalone curl command uses a fresh connection, so no body is needed; if you call these from a pooled HTTP client, send an empty body {} (see bodyless writes):

ID=899c89f9-90c3-c633-8586-8f09b005ebed

# Load the solution and models into memory
curl -X POST "http://localhost:3546/v1/core/instance/$ID/load"

# Start processing (loads automatically if not already loaded)
curl -X POST "http://localhost:3546/v1/core/instance/$ID/start"

# Stop processing
curl -X POST "http://localhost:3546/v1/core/instance/$ID/stop"

# Free the models from memory
curl -X POST "http://localhost:3546/v1/core/instance/$ID/unload"

# Restart (stop + start)
curl -X POST "http://localhost:3546/v1/core/instance/$ID/restart"

Common error responses: 404 Not Found (unknown ID), 406 Not Acceptable (the operation cannot be performed in the current state), and 403 Forbidden when start is rejected because the licensed maximum number of streams is reached.

Updating an instance ¶

Use PATCH to change instance properties in place:

curl -X PATCH "http://localhost:3546/v1/core/instance/899c89f9-90c3-c633-8586-8f09b005ebed" \
  -H "Content-Type: application/json" \
  -d '{
    "frameRateLimit": 10,
    "detectionSensitivity": "High",
    "autoStart": true
  }'

Returns 204 No Content.

Inspecting configuration, state, and statistics ¶

ID=899c89f9-90c3-c633-8586-8f09b005ebed

# Full configuration tree (input, detector, outputs, ...)
curl "http://localhost:3546/v1/core/instance/$ID/config"

# Runtime state (only available while loaded/running)
curl "http://localhost:3546/v1/core/instance/$ID/state"

# Live processing statistics
curl "http://localhost:3546/v1/core/instance/$ID/statistics"

The statistics endpoint reports throughput and latency for a running instance:

{
  "frames_processed": 15000,
  "source_framerate": 30,
  "current_framerate": 28.5,
  "latency": 42.3,
  "input_queue_size": 7,
  "dropped_frames_count": 12,
  "resolution": "1920x1080",
  "format": "BGR"
}

Individual configuration values are written with the path / jsonValue pattern described in the overview; this is how outputs are configured in the Configuring Exporting tutorial.

Deleting an instance ¶

curl -X DELETE "http://localhost:3546/v1/core/instance/899c89f9-90c3-c633-8586-8f09b005ebed"

Returns 204 No Content. A running instance is stopped first. A read-only/system instance cannot be deleted and returns 403 Forbidden.

End-to-end example ¶

The following script creates a SecuRT instance, points it at a camera, runs it, checks its throughput, and tears it down — the exact sequence used to validate this page against a live RT Server.

#!/bin/bash
BASE="http://localhost:3546"

# 1. Create the instance and capture its ID
ID=$(curl -s -X POST "$BASE/v1/core/instance" \
  -H "Content-Type: application/json" \
  -d '{"name":"Front Entrance","group":"building-a","solution":"securt","persistent":true}' \
  | python -c "import sys,json; print(json.load(sys.stdin)['instanceId'])")
echo "Created instance $ID"

# 2. Set the input source
curl -s -X POST "$BASE/v1/core/instance/$ID/input" \
  -H "Content-Type: application/json" \
  -d '{"type":"RTSP","uri":"rtsp://vid.cvedia.com:8554/gsx_demo2"}'

# 3. Start processing
curl -s -X POST "$BASE/v1/core/instance/$ID/start"

# 4. Wait, then read statistics
sleep 10
curl -s "$BASE/v1/core/instance/$ID/statistics"

# 5. Stop and delete
curl -s -X POST "$BASE/v1/core/instance/$ID/stop"
curl -s -X DELETE "$BASE/v1/core/instance/$ID"
echo "Done"

Next steps ¶

Configuring Analytics - add SecuRT areas and tripwires to your instance.
Configuring Exporting - stream the processed video and push events to MQTT.
Reading Events with SSE - subscribe to the instance's live event stream.