# API Communication

### Equivalent to `ServiceHandler.scheduler.scheduleCommand` <a href="#equivalent-to-servicehandlerschedulerschedulecommand" id="equivalent-to-servicehandlerschedulerschedulecommand"></a>

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:**

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

**Curl Example:**

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

### Equivalent to `ServiceHandler.scheduler.scheduleAction` <a href="#equivalent-to-servicehandlerschedulerscheduleaction" id="equivalent-to-servicehandlerschedulerscheduleaction"></a>

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.

```sh
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` <a href="#equivalent-to-servicehandlerschedulerupdateinputdefinition" id="equivalent-to-servicehandlerschedulerupdateinputdefinition"></a>

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).

```sh
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` <a href="#equivalent-to-servicehandlerschedulersavesettingsloadsettings" id="equivalent-to-servicehandlerschedulersavesettingsloadsettings"></a>

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.

```sh
# 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 <a href="#handling-results" id="handling-results"></a>

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.

  ```json
  {
    "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 <a href="#handling-notifications" id="handling-notifications"></a>

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):

```json
{
  "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": ""
  }
}
```