Modules

The /modules endpoint provides creation, management and direct interaction with modules outside of a system context. For more information on the role that modules play, see:

Model

Attribute

Type

Description

id

string

A universally unique ID for this module.

dependency_id

string

ID of the driver that defines this module.

control_system_id

string

ID of the system this module is bound to (logic modules only).

edge_id

string

ID of the preferred engine node to run on.

ip

string

IP address or resolvable hostname of the device this module connects to.

tls

boolean

True if the device communicates securely.

udp

boolean

Protocol uses UDP rather that TCP.

port

integer

The TCP or UDP port that the associated device communicates on.

makebreak

boolean

If enabled, provides an ephemeral connection that disconnects during idle periods.

uri

string

The based URI of the remote service (service modules only).

custom_name

string

The modules class name (Display, Lighting etc) if it should differ from the default defined in the dependency.

settings

object

A JSON object containing module configuration.

updated_at

integer

Timestamp of last update.

created_at

integer

Timestamp of creation.

role

integer

The module type. One of:

0 ssh

1 device

2 service

3 logic

notes

string

Markdown formatted text that describes this module.

connected

boolean

Flag for connectivity state.

running

boolean

Module start/stop state.

ignore_connected

boolean

If enabled, system metrics ignore connectivity state.

ignore_startstop

boolean

If enabled, system level start and stop actions are ignored. This is recommended for modules shared by many systems (e.g. a lighting gateway).

Discovery

https://aca.example.com/api/control/modules
List or search for existing modules.
Request
Response
Query Parameters
q
optional
string
A search filter to apply.
limit
optional
integer
(default 20) Max results to return.
offset
optional
integer
The offset within the result set.
system_id
optional
string
Return modules associated with the specified system.
dependency_id
optional
string
Return modules that are an instance of the specified dependency.
200: OK
{
"total": 1,
"results": [
{
"dependency_id": "dep-wJHShR4Ffa",
"control_system_id": null,
"edge_id": "edge-E9vIruSZ",
"ip": "10.45.6.3",
"tls": false,
"udp": false,
"port": 8192,
"makebreak": false,
"uri": null,
"custom_name": null,
"settings": {},
"updated_at": 1572412023,
"created_at": 1572392714,
"role": 1,
"connected": true,
"running": true,
"notes": null,
"ignore_connected": false,
"ignore_startstop": false,
"id": "mod-wJHYeHm6Yn"
}
]
}

Queries default to searching for any of the entered terms (words). A small query language provides the ability to structure complex queries.

Operator

Action

+

Matches both terms.

|

Matches either terms.

-

Negates a single token.

"

Wraps tokens to form a phrase.

( and )

Provide precedence.

~N

Specifies edit distance (fuzziness) after a word.

~N

Specifies slop amount (deviation) after a phrase.

Management

post
Create

https://aca.example.com/api/control/modules
Creates a new module.
Request
Response
Body Parameters
dependency_id
required
string
edge_id
required
string
control_system_id
optional
string
required for logic modules
ip
optional
string
required for ssh and device modules
udp
optional
boolean
port
optional
integer
makebreak
optional
boolean
uri
optional
string
required for service modules
custom_name
optional
string
settings
optional
object
notes
optional
string
ignore_connected
optional
boolean
ignore_startstop
optional
boolean
200: OK
Successful creations will return the full module.
{
"dependency_id": "dep-wJHShR4Ffa",
"control_system_id": null,
"edge_id": "edge-E9vIruSZ",
"ip": "10.45.6.3",
"tls": false,
"udp": false,
"port": 8192,
"makebreak": false,
"uri": null,
"custom_name": null,
"settings": {},
"updated_at": 1572412023,
"created_at": 1572412023,
"role": 1,
"connected": true,
"running": true,
"notes": null,
"ignore_connected": false,
"ignore_startstop": false,
"id": "mod-wJHYeHm6Yn"
}
406: Not Acceptable
Missing or invalid module configuration.
{
"dependency_id": ["can't be blank"]
}

get
Retrieve

https://aca.example/com/api/control/modules/{id}
Retrieve all metadata associated with a module.
Request
Response
Path Parameters
id
required
string
ID of the modules to retrieve.
200: OK
{
"dependency_id": "dep-wJHShR4Ffa",
"control_system_id": null,
"edge_id": "edge-E9vIruSZ",
"ip": "10.45.6.3",
"tls": false,
"udp": false,
"port": 8192,
"makebreak": false,
"uri": null,
"custom_name": null,
"settings": {},
"updated_at": 1572412023,
"created_at": 1572412023,
"role": 1,
"connected": true,
"running": true,
"notes": null,
"ignore_connected": false,
"ignore_startstop": false,
"id": "mod-wJHYeHm6Yn"
}
404: Not Found

put
Update

https://aca.example.com/api/control/modules/{id}
Updates module attributes or configuration.
Request
Response
Path Parameters
id
required
string
ID of the module to update.
Body Parameters
control_system_id
optional
string
edge_id
optional
string
ip
optional
string
udp
optional
boolean
port
optional
integer
makebreak
optional
boolean
uri
optional
string
custom_name
optional
string
settings
optional
object
notes
optional
string
ignore_connected
optional
boolean
ignore_startstop
optional
boolean
200: OK
Module updated.
{
"dependency_id": "dep-wJHShR4Ffa",
"control_system_id": null,
"edge_id": "edge-E9vIruSZ",
"ip": "10.45.6.3",
"tls": false,
"udp": false,
"port": 8192,
"makebreak": false,
"uri": null,
"custom_name": null,
"settings": {},
"updated_at": 1572412023,
"created_at": 1572414543,
"role": 1,
"connected": true,
"running": true,
"notes": null,
"ignore_connected": false,
"ignore_startstop": false,
"id": "mod-wJHYeHm6Yn"
}
403: Forbidden
The user does not have permissions to update this module.
404: Not Found
The passed module ID does not exist.
406: Not Acceptable
Validation error.

delete
Delete

https://aca.example/com/api/control/modules/{id}
Removes a module. Modules that are associated with multiple systems be removed from all.
Request
Response
Path Parameters
id
required
string
ID of the module to delete.
200: OK
403: Forbidden
404: Not Found

Interaction

post
Start

https://aca.example.com/api/control/modules/{id}/start
Starts a module on it's associated control node.
Request
Response
Path Parameters
id
required
string
ID of the module to start.
200: OK
Module started.
403: Forbidden
404: Not Found
500: Internal Server Error
An error occurred that prevented the module from starting.

post
Stop

https://aca.example.com/api/control/modules/{id}/stop
Stops the module. Exposed state will still be available but will not update.
Request
Response
Path Parameters
id
required
string
ID of the module to stop.
200: OK
403: Forbidden
404: Not Found

post
Ping

https://aca.example.com/api/control/modules/{id}/ping
Performs a connectivity check with the associated device or service.
Request
Response
Path Parameters
id
required
string
ID of the module to check.
200: OK
{
"host": "10.45.5.2",
"pingable": true,
"warning": null,
"exception": null
}
406: Not Acceptable
The module specified is a logic module.

get
State

https://aca.example.com/api/control/modules/{id}/state
Gets the state information exposed by a module.
Request
Response
Path Parameters
id
required
string
ID of the module to query.
Query Parameters
lookup
optional
string
Status key of interest. If included, the response filters to this value.
200: OK
{
"foo": "abc",
"bar": 42
}