API Communication

Equivalent to ServiceHandler.scheduler.scheduleCommand

To call scheduleCommand, send a JSON-encoded string that will decode to an object with the following fields:

• command: string. The name of the command to run.

• parameters: object. The parameters as an object.

• variables: object. The variables as an object.

Netcat Example:

MSG=$'{"command": "readTitle", "parameters":{"title":"Test"}}\r\n'
( echo $MSG; sleep 1; ) | nc localhost 9025

Curl Example:

curl --data '{"command": "readTitle", "parameters":{"title":"Test"}}' \
     -H 'Content-Type: application/json' \
     http://localhost:9022/api/

Equivalent to ServiceHandler.scheduler.scheduleAction

To call scheduleAction, send a JSON-encoded string that will decode to an object with the following fields:

• action: string. The name of the action to schedule.

• input: string. The name of the input/data controller to target, leave blank to target all.

• title: string. The id or name of the title/graphic layer to target, leave blank to target all.

• variables: object. The variables as an object.

curl --data '{"action": "update", "title": "My Title", "variables": {"Time": "00:00", "Message": "Go!"}}' \
     -H 'Content-Type: application/json' \
     http://localhost:9022/api/

Equivalent to ServiceHandler.scheduler.updateInputDefinition

To call updateInputDefinition, send a JSON-encoded string that will decode to an object with the following fields:

• redefine: string. The name of the input/data controller to target.

• definition: object. The variables “definition” object (see updateInputDefinition on the JavaScript API documentation).

curl --data '{"redefine": "My Input", {"method": "merge", "variables": {"Clock":{"pattern":"[0-9][0-9]:[0-9][0-9]"}}}}' \
     -H 'Content-Type: application/json' \
     http://localhost:9022/api/

Equivalent to ServiceHandler.scheduler.saveSettings/loadSettings

To call saveSettings or loadSettings, send a JSON-encoded string that will decode to an object with the following fields:

• settings: object|string. For loading, use the word load. For saving, use an object or any string other than load.

• input: string. The name of the input / data controller for which to load or save settings.

# save {"name": "value"} to the settings
curl --data '{"input":"API Tour: JSON Command Tester", "settings": {"name":"value"}}' \
     -H 'Content-Type: application/json' \
     http://localhost:9022/api/
# {"result":null}

# load from the settings
curl --data '{"input":"API Tour: JSON Command Tester", "settings": "load"}' \
     -H 'Content-Type: application/json' \
     http://localhost:9022/api/
# {"result":{"name":"value"}}

Handling Results

The results of an advanced API call will be exactly the same as the main JavaScript API with the following modifications:

• Successful responses will be wrapped in an object where result is the key to the actual Captivate response.

  {
    "result": {
      "command": "schedule",
      "reply": "schedule",
      "success": true
    }
  }

• If Captivate’s normal response included a file (referring to a filepath on the Captivate computer’s filesystem), the wrapped response will also include a url field pointing to the same file, but made available over HTTP.

• If the call failed somehow, the response will be {"error": "scheduleCommand failed", "data": [javascript error object] }

• If the call is one of the asynchronous commands that passes information back through the notification system, you will need to be subscribed to notifications to receive it. See below.

Handling Notifications

When a client connects to the TCP socket or issues an HTTP GET to /api/subscribe, it will immediately be subscribed to all play and data events sent from Captivate. Whenever a notification message is received from Captivate, it is passed to the client as a JSON-encoded string terminated with CRLF (\r). As with command results, this reply will have additional url fields whenever a file field is found in the response from Captivate.

The UDP endpoint does not support Captivate’s notification stream.

Notification messages will be wrapped in an object where notification is the key to the actual notification content (or error as above if there was an error subscribing to the notification stream):

{
  "notification": {
    "channel": -1,
    "command": "notify",
    "event": "play",
    "id": "{cd654eba-4afe-4838-ad75-65ff823ac0dd}",
    "input": "",
    "play": "Running",
    "sender": "", // `sender` as given in the parameters of the "subscribe" command
    "title": "Acrylic Baseball Scoreboard",
    "to": ""
  }
}