Skip to main content

API Discovery

The server generates its command catalog and OpenAPI document at runtime. Both describe what the running server accepts.

The catalog lists DisplayNet API operations. The OpenAPI document also exposes the generic SDVoE device passthrough. It does not enumerate SDVoE API operation bodies or every SDVoE resource. Use SDVoE API operations as the starting point for those requests.

The command catalog​

Catalog endpoint​

GET /api/commands

This endpoint returns every DisplayNet API operation and its parameters. It does not list SDVoE API operations because those belong to the SDVoE API's resource paths.

Version and surface fingerprint​

The response result wraps the catalog alongside the engine version and a fingerprint of the operation surface, so a client can confirm it is talking to a build new enough for the operations it depends on before it calls them.

{
  "status": "SUCCESS",
  "result": {
    "engine": { "version": "4.3.0.local", "app_version": "4.7.0.2612" },
    "api": { "op_count": 191, "hash": "sha256:1f3c…" },
    "commands": [ /* catalog entries, below */ ]
  }
}
FieldDescription
engine.versionThe engine assembly version — the same value the socket handshake reports.
engine.app_versionThe application build version.
api.op_countHow many operations the catalog contains.
api.hashA stable fingerprint of the operation surface — each operation's name, aliases, and parameter shapes. It changes whenever an operation or parameter is added, removed, or changed, and is unaffected by description wording. Store it and compare on the next connection to detect that the surface has changed.

Example catalog entry​

{
  "op": "preset_get",
  "command": "preset",
  "subcommand": "get",
  "aliases": [],
  "description": "Get a preset's contents (snapshot or script)",
  "parameters": [
    {
      "name": "name",
      "type": "string",
      "optional": false,
      "rest": false,
      "description": ""
    }
  ]
}
FieldDescription
opThe operation name to call
command / subcommandThe equivalent TCI command, split into its parts
aliasesAlternative spellings the command also answers to
descriptionWhat the command does
parametersEach parameter's name, type, and whether it is optional
parameters[].restWhen true, this parameter captures all remaining input

The OpenAPI specification​

OpenAPI endpoint​

GET /api/openapi.json

This endpoint returns an OpenAPI 3.0.3 document. It describes each DisplayNet API operation as its own path, along with the request body schemas, response envelope, and bearer security scheme. It also includes the generic /api/device/{target} SDVoE API passthrough path.

The document does not enumerate individual SDVoE API op bodies or the /api/event and /api/request/{request_id} resources. A generated client covers the DisplayNet API portion. Use SDVoE API operations for the remaining resource paths and request bodies.

Each operation also carries x-displaynet-min-role. This is the minimum role required to call it. A generated client can check that value before making a request. The document's info.version field reports the engine version.

Point any OpenAPI tool at the URL:

ToolUse
Swagger UIBrowse the operations and try them against the live server
PostmanImport the URL to get a ready-made collection
Client generatorsProduce a typed client

Swagger UI is not bundled on the server. Use your own instance and give it the URL.

Unlisted commands​

Two categories of command are absent from both endpoints.

Commands with no REST operation. Calling one returns UNKNOWN_OP. The command map lists them.

Session commands. mode, logintoken, and password require an interactive session. REST has no such session, so these commands are never exposed as REST operations.

See also​