A RESTful API is an architectural style for an application program interface (API) that uses HTTP requests to access and use data. That data can be used to GET, PUT, POST, and DELETE data types, referring to the reading, updating, creating, and deleting operations concerning resources. 

REST API is a licensed feature. For more details, please contact with our Licensing Team.

Base URL: Your current RealityHub address and port (ex: http://localhost) 

Endpoint:  Communication channel that you want to do some process (/api/rest/v1/engines/1/nodes) 

If the Endpoint contains characters that the URL doesn't support, those characters should be URL-Encoded. For more information, please visit: HTML URL Encoding Reference

GET 

Retrieve a specific resource or a collection of resources and always returns data. GET can be used for:

  • Engine details (name, status, host id, IP, hostname)

  • Nodes (All nodes in an active RGraph) 

  • Node functions (All functions and values of a specific node) 

  • Node properties (All properties and values that includes in a specific node) 

  • Rundowns (rundown ID, items, values)

Examples for GET

End Point

Description

GET /api/rest/v1/engines 

Lists all engines and their information added to the system

Example Response:

[
  {
    "id": 7,
    "name": "HUBSERVER",
    "ip": "127.0.0.1",
    "role": "Broadcast",
    "status": "connected",
    "cacheDir": "c:\\cache",
    "minimumFreeSpace": 209715200,
    "usedSpace": 292844453888,
    "diskSpace": 500724768768,
    "canCook": true,
    "displayName": "HUBSERVER",
    "enabled": true,
    "port": 6666,
    "rgraphId": 3,
    "ownerStudioId": 4,
  }
] 
JSON

/api/rest/v1/engines/1 

Lists engine information that id equals to “1”

/api/rest/v1/engines/1/nodes 

Lists all nodes on engine that id is equal to “1” 

Example Response:

[
  {
    "NodePath": "EngineControl"
  },
  {
    "NodePath": "Camera_0"
  },
  {
    "NodePath": "UserTrack_0"
  }
]
CODE

/api/rest/v1/engines/1/nodes/EngineControl/properties

 Lists all properties and their values on EngineControl node 

Example Response:

[
  {
    "MemberName": "KeepAlive",
    "Value": true,
    "PropertyPath": "Device//KeepAlive/0",
    ...
  },
  {
    "MemberName": "CoordinateSystem",
    "Value": "XYZ",
    "PropertyPath": "Transform Mapping//CoordinateSystem/0",
    ...
  },
  ...
]
CODE

/api/rest/v1/engines/1/nodes/EngineControl/functions

 Lists all functions and their values on EngineControl node 

Example Response:

[
  {
    "FunctionPath": "Default//ForceGarbageCollection/0"
  },
  {
    "FunctionPath": "Default//Sync/0"
  },
  {
    "FunctionPath": "Default//UpdateLicenseInfo/0"
  },
  {
    "FunctionPath": "Default//RemoveWatermark/0"
  },
  {
    "FunctionPath": "Default//Refresh/0"
  }
]
CODE

/api/rest/v1/playout/rundowns

Lists all the rundowns and their ID’s. 

Example Response:

[
  {
    "id": 11,
    "name": "New Rundown"
  }
]
CODE

/api/rest/v1/playout/rundowns/12/items

 Lists all the items on rundown that rundown id is equal to “12” 

Example Response:


  {
    "id": 32,
    "name": "New Form"
  }
]
CODE

/api/rest/v1/playout/templates 

Lists all the templates on RealityHub db 

Example Response:

[
  {
    "id": 12,
    "name": "My First Form"
  },
  {
    "id": 13,
    "name": "Weather_0"
  }
]
CODE

POST 

POST method is used to modify and update a resource. POST can be used for updating function values clicking buttons, adding rundown items, etc. 

Example: 

/api/rest/v1/engines/1/nodes/EngineControl/functions with this endpoint and GET method, you listed all functions below to EngineControl node, and you want to click to RemoveWatermark button with POST method. 

Examples for POST 

POST /api/rest/v1/engines/1/nodes/EngineControl/functions/Default%2F%2FRemoveWatermark%2F0

  • This call requires no request body

Triggers the “RemoveWatermark” function of EngineControl node

{
    "success": true
}
JSON

/api/rest/v1/playout/rundowns/12/items

Example Request Body:

{ 
  "template": "MyTemplate01", 
  "name": "NewRundownItem01" 
} 
CODE

Create new rundown “NewRundownItem01” in the rundown (with ID 12), referencing to the template “MyTemplate01”.

Example Response Body:

{
    "id": 15,
    "name": "NewRundownItem01",
    "template": "MyTemplate01",
    "data": {}
}
JSON

PATCH 

The PATCH method is used to make changes to a part of the resource at a location. PATCH can be used for updating a function and property values. 

Examples for PATCH

PATCH /api/rest/v1/engines/1/nodes/Camera_0/properties/Render%2F%2FRenderSize%2F0

Example Request Body:

{
    "Value": { 
      "X": 1920, 
      "Y": 1080 
    }
}
CODE

 Changes Render Size property value to 1920*1080 on Camera node 

Example Response Body

{
    "PropertyPath": "Render//RenderSize/0",
    "Value": {
        "X": 1920,
        "Y": 1080
    }
}
JSON

PATCH /api/rest/v1/playout/rundowns/12/items/34 

Example Request Body:

  { 
      "name": "WillBeDeleted" 
  }
CODE

Rename a rundown’s (12) item (34 )

Example Response Body:

{
    "id": 34,
    "name": "WillBeDeleted",
    "template": "MyTemplate01",
    "data": {}
}
JSON

DELETE 

The DELETE method requests that the origin server delete the resource recognized by the Request-URI. Returns 204 message 

The DELETE can be used to deleting a rundown item.

Examples for DELETE

End Point

Description

DELETE /api/rest/v1/playout/rundowns/12/items/34

Deletes rundown with id:12 and item with id:34 

There is no Response Body when an operation is successful.