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

{% content-ref url="/pages/-LZYWTmew5\_uwlwgJJ\_P" %}
[Modules](/key-concepts/modules.md)
{% endcontent-ref %}

## 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` | <p>The module type. One of:</p><p><code>0</code> ssh</p><p><code>1</code> device</p><p><code>2</code> service</p><p><code>3</code> logic</p> |
| ---- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |

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

## Search

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/modules`

List or search for existing modules.

#### Query Parameters

| Name           | Type    | Description                                                      |
| -------------- | ------- | ---------------------------------------------------------------- |
| q              | string  | A search filter to apply.                                        |
| limit          | integer | (default 20) Max results to return.                              |
| offset         | integer | The offset within the result set.                                |
| system\_id     | string  | Return modules associated with the specified system.             |
| dependency\_id | string  | Return modules that are an instance of the specified dependency. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "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"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

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

## Create

<mark style="color:green;">`POST`</mark> `https://example.com/api/control/modules`

Creates a new module.

#### Request Body

| Name                | Type    | Description                         |
| ------------------- | ------- | ----------------------------------- |
| dependency\_id      | string  |                                     |
| edge\_id            | string  |                                     |
| control\_system\_id | string  | required for logic modules          |
| ip                  | string  | required for ssh and device modules |
| udp                 | boolean |                                     |
| port                | integer |                                     |
| makebreak           | boolean |                                     |
| uri                 | string  | required for service modules        |
| custom\_name        | string  |                                     |
| settings            | object  |                                     |
| notes               | string  |                                     |
| ignore\_connected   | boolean |                                     |
| ignore\_startstop   | boolean |                                     |

{% tabs %}
{% tab title="200 Successful creations will return the full module." %}

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

{% endtab %}

{% tab title="406 Missing or invalid module configuration." %}

```javascript
{
  "dependency_id": ["can't be blank"]
}
```

{% endtab %}
{% endtabs %}

## Retrieve

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/modules/{id}`

Retrieve all metadata associated with a module.

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| id   | string | ID of the modules to retrieve. |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="404 " %}

```
```

{% endtab %}
{% endtabs %}

## Update

<mark style="color:orange;">`PUT`</mark> `https://example.com/api/control/modules/{id}`

Updates module attributes or configuration.

#### Path Parameters

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| id   | string | ID of the module to update. |

#### Request Body

| Name                | Type    | Description |
| ------------------- | ------- | ----------- |
| control\_system\_id | string  |             |
| edge\_id            | string  |             |
| ip                  | string  |             |
| udp                 | boolean |             |
| port                | integer |             |
| makebreak           | boolean |             |
| uri                 | string  |             |
| custom\_name        | string  |             |
| settings            | object  |             |
| notes               | string  |             |
| ignore\_connected   | boolean |             |
| ignore\_startstop   | boolean |             |

{% tabs %}
{% tab title="200 Module updated." %}

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

{% endtab %}

{% tab title="403 The user does not have permissions to update this module." %}

```
```

{% endtab %}

{% tab title="404 The passed module ID does not exist." %}

```
```

{% endtab %}

{% tab title="406 Validation error." %}

```
```

{% endtab %}
{% endtabs %}

## Delete

<mark style="color:red;">`DELETE`</mark> `https://example.com/api/control/modules/{id}`

Removes a module. Modules that are associated with multiple systems be removed from all.

#### Path Parameters

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| id   | string | ID of the module to delete. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}

{% tab title="403 " %}

```
```

{% endtab %}

{% tab title="404 " %}

```
```

{% endtab %}
{% endtabs %}

## Interaction

## Start

<mark style="color:green;">`POST`</mark> `https://example.com/api/control/modules/{id}/start`

Starts a module on it's associated control node.

#### Path Parameters

| Name | Type   | Description                |
| ---- | ------ | -------------------------- |
| id   | string | ID of the module to start. |

{% tabs %}
{% tab title="200 Module started." %}

```
```

{% endtab %}

{% tab title="403 " %}

```
```

{% endtab %}

{% tab title="404 " %}

```
```

{% endtab %}

{% tab title="500 An error occurred that prevented the module from starting." %}

```
```

{% endtab %}
{% endtabs %}

## Stop

<mark style="color:green;">`POST`</mark> `https://example.com/api/control/modules/{id}/stop`

Stops the module. Exposed state will still be available but will not update.

#### Path Parameters

| Name | Type   | Description               |
| ---- | ------ | ------------------------- |
| id   | string | ID of the module to stop. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}

{% tab title="403 " %}

```
```

{% endtab %}

{% tab title="404 " %}

```
```

{% endtab %}
{% endtabs %}

## Ping

<mark style="color:green;">`POST`</mark> `https://example.com/api/control/modules/{id}/ping`

Performs a connectivity check with the associated device or service.

#### Path Parameters

| Name | Type   | Description                |
| ---- | ------ | -------------------------- |
| id   | string | ID of the module to check. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "host": "10.45.5.2",
  "pingable": true,
  "warning": null,
  "exception": null
}
```

{% endtab %}

{% tab title="406 The module specified is a logic module." %}

```
```

{% endtab %}
{% endtabs %}

## State

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/modules/{id}/state`

Gets the state information exposed by a module.

#### Path Parameters

| Name | Type   | Description                |
| ---- | ------ | -------------------------- |
| id   | string | ID of the module to query. |

#### Query Parameters

| Name   | Type   | Description                                                              |
| ------ | ------ | ------------------------------------------------------------------------ |
| lookup | string | Status key of interest. If included, the response filters to this value. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "foo": "abc",
  "bar": 42
}
```

{% endtab %}
{% endtabs %}


---

# 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://engine.place.technology/api/control/modules.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.