This guide explains a basic example of how to read and update a device's Outputs shadow using Postman. The same patterns apply to other shadows (System, Inputs, Encoders, Alerts, Containers).

Helpful Tip!

When in doubt, open the LiveEdge® Cloud UI at https://videoncloud.com/ and watch network traffic in your browser's developer tools (F12). The UI’s calls are the gold-standard examples of real payloads and field names.

Table of contents:

• What is a "Shadow"?
• Prerequisites
• Postman Setup
  • 1) Create a Postman environment
  • 2) Authorization
• Key APIs
  • Get Device Shadow
  • Send Shadow Command
  • Check Shadow Command Status
• Step‑by‑Step: Read & Update the Outputs Shadow
  • Step 1: GET the current Outputs shadow
  • Step 2: Prepare your SET payload
  • Step 3: Track the command by command_guid
• More Outputs Examples
  • Create a new RTMP output
  • Delete an output
• Do's and Don'ts (for all Shadows)
• Troubleshooting
• Final notes
• FAQ
  • How do I create/delete a component (an output, encoder, input, etc.)?
  • What are the options for components that can be configured via Shadows?

What is a "Shadow"?

A shadow is a single-page configuration document persisted to a Videon device. Devices expose multiple shadows, so you can configure independent areas of the device without touching others.

Each shadow tracks two perspectives:

• reported - the current device state (authoritative snapshot produced by the device/Cloud).
• requested - the latest command that was sent for that shadow, along with its status.

Authorization: PAT <your-PAT-token>

Key APIs

Get Device Shadow

• https://api.videoncloud.com/v1/openapi/html#operation/GetDeviceShadow
• GET {{base_url}}/devices/{{device_guid}}/shadows
  Optional query parameters:
  • shadow_names=Outputs - target a specific shadow
  • skip_requested_state=true - hide the requested block for a cleaner payload to copy
     

Send Shadow Command

• https://api.videoncloud.com/v1/openapi/html#operation/SendDeviceShadowCommand
• POST {{base_url}}/devices/{{device_guid}}/shadows/commands
  Body includes your command_type, commands[], target_version, and the full state.

Check Shadow Command Status

• https://api.videoncloud.com/v1/openapi/html#operation/GetDeviceShadowCommand
• GET {{base_url}}/devices/{{device_guid}}/shadows/commands/{{command_guid}}
  Use the command_guid returned by the Send Shadow Command call to track success/failure and completion.

GET {{base_url}}/devices/{{device_guid}}/shadows?shadow_names=Outputs&skip_requested_state=true

{
    "shadows": [
        {
            "shadow_name": "Outputs",
            "requested": null,
            "reported": {
                "state": [
                    {
                        "status_message": "Running",
                        "id": 19,
                        "status_code": "RUNNING",
                        "type": "thumbnail",
                        "config": {
                            "name": "",
                            "width": 320,
                            "interval": 5,
                            "sources": {
                                "data": [],
                                "audio": [],
                                "video": [
                                    170
                                ]
                            },
                            "enable": true
                        }
                    },
                    {
                        "status_message": "Off",
                        "id": 173,
                        "status_code": "OFF",
                        "type": "rtmp",
                        "config": {
                            "name": "RTMP 173",
                            "service_data": "{\n}\n",
                            "sources": {
                                "data": [],
                                "audio": [],
                                "video": []
                            },
                            "enable": false,
                            "service_name": "generic"
                        },
                        "status": "STREAM_OFF"
                    }
                ],
                "current_version": 2,
                "timestamp": "{timestamp}"
            }
        }
    ],
    "operation_name": "GetDeviceShadow",
    "api_request_id": "{request_id}"
}

POST {{base_url}}/devices/{{device_guid}}/shadows/commands

{
  "command_type": "set",
  "commands": [
    {
      "shadow_name": "Outputs",
      "target_version": 3,
      "state": [
        {
          "id": 19,
          "type": "thumbnail",
          "config": {
            "name": "",
            "width": 320,
            "interval": 5,
            "sources": { "data": [], "audio": [], "video": [170] },
            "enable": true
          }
        },
        {
          "id": 173,
          "type": "rtmp",
          "config": {
            "name": "YouTube RTMP",
            "service_name": "generic",
            "service_data": "{\n \"url\": \"rtmp://myrtmpurl/mystreamkey\"\n}\n",
            "sources": { "data": [], "audio": [], "video": [] },
            "enable": true
          }
        }
      ]
    }
  ]
}

{
    "command_type": "set",
    "commands": [
        {
            "shadow_name": "Outputs",
            "command_guid": "{command_guid}"
        }
    ],
    "operation_name": "SendDeviceShadowCommand",
    "api_request_id": "{request_id}"
}

GET {{base_url}}/devices/{{device_guid}}/shadows/commands/{{command_guid}}

POST {{base_url}}/devices/{{device_guid}}/shadows/commands

{
  "command_type": "set",
  "commands": [
    {
      "shadow_name": "Outputs",
      "target_version": <current_version + 1>,
      "state": [
        /* existing outputs copied from reported.state */,
        {
          "id": false,
          "type": "rtmp",
          "config": {
            "name": "CDN A",
            "service_name": "generic",
            "service_data": "{\n  \"url\": \"rtmp://example.com/live/abcd1234\"\n}\n",
            "sources": { "data": [], "audio": [], "video": [] },
            "enable": true
          }
        }
      ]
    }
  ]
}

Final notes

Device shadows can be confusing at first glance, but the above examples can be expanded to configure many outputs or other settings on Videon devices, via just a couple LiveEdge Cloud API calls. If you run into issues please reach out to Tech Support and Videon can help get your workflow unblocked!

To advance to the next level of shadow commands, feel free to advance to the following article: How to control Videon devices with Shadows 201

FAQ

How do I create/delete a component (an output, encoder, input, etc.)?

Since shadows are single-page configurations, all that needs to be done to both create and delete components is to either include the new desired with id: false, or not include any non-desired components in the Body of the POST request, and the shadow will be applied, either adding the newly included components or removing the excluded components.

This is useful in reducing the number of calls needed to be made when configuring multiple components, but be careful not to accidentally delete a component by not including it in the shadow, even if it is not receiving any new changes!

What are the options for components that can be configured via Shadows?

Since we are often adding new options and features to LiveEdge Cloud's capabilities, the best way to know the current possible options for any component/function is to use our Cloud UI with the browser console open (F12 in Chrome) and mimic the calls that our UI makes to the LiveEdge Cloud API.