Skip to main content

REST API

The DisplayNet REST server exposes two endpoint types through one HTTP interface. One handles DisplayNet API commands. The other exposes SDVoE API commands.

Use a DisplayNet API command whenever one covers the operation. DisplayNet tracks the resulting state, so this is usually the easier option. Use an SDVoE API command when no DisplayNet command covers the operation or when you need lower-level control.

A client written for the SDVoE REST API works against a DisplayNet server unchanged. The DisplayNet REST server exposes the SDVoE API endpoints, so the client does not need a second HTTP connection. The two endpoint types use different paths and request bodies.

Endpoint typesDisplayNet API commands and SDVoE API commands
DisplayNet minimum version4.6

Base URL​

The REST API is served at /api on the DisplayNet Server's normal web ports. Use port 443 for HTTPS and port 80 for HTTP. There is no separate REST port.

https://<server>/api

The server's default hostname is displaynet.local.

REST endpoints​

The interface carries two endpoint types. Choose the endpoint type before choosing the request form:

Endpoint typeUse it forEndpoints
DisplayNet API commandsRouting, presets, walls, MultiView, tagging, server administration, and other DisplayNet commandsPOST /api/displaynet/<operation> or POST /api/displaynet
SDVoE API commandsDevice resources, stream control, device configuration, event polling, and asynchronous request polling/api/device/*, /api/event, /api/request/*

The endpoint types use different paths and request bodies. For example, a DisplayNet API operation such as preset_get goes to /api/displaynet. An SDVoE API operation such as start goes to /api/device/<target>. See Sending commands and SDVoE API operations for the request bodies.

Transports​

A command sent over REST behaves exactly as it does over telnet.

TransportEndpointBest for
Telnetport 6980Control systems, scripting, interactive exploration
TCI WebSocketport 7000, or 7010 for TLSWeb applications that want a full API session
REST/api on 80/443Web clients, integrations, anything that already speaks HTTP
REST WebSocket/api on 80/443, upgradedReceiving notifications without polling

REST is a good fit for a client that already has an HTTP stack or needs to cross a firewall or proxy. It also works well when you want to generate a client from the OpenAPI spec.

TCI WebSocket vs REST WebSocket

The TCI WebSocket on ports 7000 and 7010 is a full API session. It uses the same commands and responses as a telnet session. Before sending commands, the client must navigate the connection state, including require api and mode async on. DisplayNet Manager uses this endpoint. See Connecting to the API.

The REST WebSocket upgrades /api on ports 80 and 443. It supports SDVoE REST API events and adds DisplayNet notifications on the same connection. Events begin flowing as soon as the client connects; no setup command is required. See WebSocket.

Request types​

A command request under /api goes to one of two endpoint types: a DisplayNet API operation or an SDVoE API operation. The request path determines which type handles it.

A DisplayNet API operation. These commands are listed in the Command Reference and exposed under /api/displaynet. The operation name joins the command and subcommand with an underscore. For example, preset list becomes preset_list.

POST /api/displaynet/preset_list
POST /api/displaynet/preset_list

An SDVoE API operation. Requests on /api/device/*, /api/event, and /api/request/* are forwarded to the Control Server. See SDVoE API operations.

POST /api/device/<device>
POST /api/device/<device>

Both endpoint types return the same response envelope, so a client can use the same parser for both. See Responses and errors.

REST availability​

Some commands have no REST operation. The command map lists them. Calling an unpublished DisplayNet command returns an error:

POST /api/displaynet/version
{
  "status": "ERROR",
  "request_id": null,
  "result": null,
  "error": {
    "message": "Unknown op 'version' (see GET /api/commands for available ops)",
    "reason": "UNKNOWN_OP"
  }
}

Some commands are withheld from REST because they only make sense inside an interactive session. They do not appear in the catalog or the spec.

The server generates its DisplayNet API operation list at runtime. GET /api/commands and GET /api/openapi.json report what the connected server supports. Neither endpoint lists individual SDVoE API operations; those are documented under the SDVoE resource paths. See API Discovery.

In this section​

See also​