Connectors

A Connector is a project-defined HTTP trigger that bundles a saved sequence of API commands behind a named endpoint, so external systems can drive the show by name (RollSting, LowerThirdOn) rather than re-wiring individual /api/setproperty and /api/invokecommand calls. Connectors can also call an optional OnConnector{Name} script function whose return value shapes the HTTP response — see the Script return-value contract below. For the authoring workflow, see User Guide → Connectors.

GET /api/connector/list

Lists all configured API connectors.

Parameters: None

Response: 200 OK — JSON array:

[
  { "Id": "guid", "Name": "My Connector", "IsActive": true, "InvokeCount": 0, "Description": "" }
]

GET /api/connector/trigger

Triggers one or more API connectors. If the project's script has an OnConnector{Name} function for the matching connector, its return value shapes the HTTP response (see Script return-value contract below).

Parameters:

Parameter	Required	Description
`name`	No*	Connector name. Use `+` to trigger multiple (e.g. `ConnA+ConnB`).
`value`	No*	Trigger value string

*At least one of name or value is required.

Additional query parameters (beyond apikey, name, value) are forwarded to the connector as parameters.

Behavior:

If ConnectorRestrictions is set to WarnAndProhibit and a connector is already running, the call is rejected with 409 Conflict.
For multi-name calls (name=A+B+C), each connector's OnConnector{name} runs in turn; the first one that returns a usable value wins as the HTTP response.
Case-insensitive. The query parameter keys (name, value) and the connector name lookup are both matched without regard to case — ?Name=Foo, ?NAME=foo, and ?name=FOO all resolve to a connector named Foo.

Response:

Custom status / body / content type — when the matching OnConnector{name} script returns a usable value (see contract below).
202 Accepted — fallback text/html body Successfully dispatched connector trigger ApiTriggerName: {name}, ApiTriggerValue: {value} when no script returned anything.
400 Bad Request — Missing parameters or connector not found
409 Conflict — Another connector is already running (when restrictions apply)

Script return-value contract details

The same contract applies to /api/scriptengine/execute. The mapping from the JS function's return value to the HTTP response is:

Script returns	HTTP response
`string` (non-empty)	`200 OK`, `Content-Type: text/plain`, body = string
object / array	`200 OK`, `Content-Type: application/json`, body = JSON-serialized value
object with a numeric `httpStatus` field, with a `body` field — explicit envelope `{ httpStatus, body, contentType? }`	status from `httpStatus`; body = `body` (string → `text/plain`, object → `application/json`); content type override via optional `contentType` (full header value, e.g. `"Content-type: text/html; charset=utf-8"`)
object with a numeric `httpStatus` field, no `body` field — hybrid shape `{ ..., httpStatus }`	status from `httpStatus`; body = the remaining fields (everything except `httpStatus` and `contentType`) serialized as JSON
`undefined`, `null`, empty string, or no return statement	falls back to the endpoint's default message
function not defined / script engine disabled / engine errored	falls back to the endpoint's default message

Notes:

A non-numeric httpStatus value is treated as a regular payload field — the whole object is serialized as JSON 200 OK and a warning is logged.
An empty body forces the response to 204 No Content regardless of the requested status (HttpListener behavior).
Status codes pass through verbatim; HttpListener rejects obviously-invalid codes and the endpoint returns 400 in that case.

Examples (script function bodies):

// Plain text
function OnConnectorStartDemo() { return "Demo started"; }
// → 200 text/plain "Demo started"

// JSON 200 OK
function OnConnectorListScenes() { return Project.Scenes.map(s => s.Name); }
// → 200 application/json ["Main","Standby"]

// Hybrid: error response with custom status
function OnConnectorShowMultipliers() {
    return { result: "error", message: "Demo mode active", httpStatus: 400 };
}
// → 400 application/json {"result":"error","message":"Demo mode active"}

// Explicit envelope: HTML body with custom status
function OnConnectorStatusPage() {
    return {
        httpStatus: 200,
        body: "<h1>Composer is up</h1>",
        contentType: "Content-type: text/html; charset=utf-8"
    };
}
// → 200 text/html <h1>Composer is up</h1>

GET /api/metadata/send

Sends a metadata message via a Vindral CDN Metadata Target.

Parameters:

Parameter	Required	Description
`targetid`	Yes	GUID of the Vindral CDN Metadata Target
`message`	Yes	Metadata message string

Example:

/api/metadata/send?targetid=guid&message=My metadata message

Response:

200 OK — Metadata sent: {url}
400 Bad Request — Missing parameters or target not found