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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.newbluefx.com/captivate-api/advanced-api-reference/api-communication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.