# API Documentation V1

### Before You Begin

Making the requests described here exposes the system you are connecting to, so credentials and tokens must be stored securely.

### Obtain Session Token

<mark style="color:green;">`POST`</mark> `https://api.ohmautomation.io/control/v1/auth`

This *endpoint* allows you to obtain the session token required to make all other requests.

**Headers**

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | string | `application/json` |

**Request Body**

| Name                                       | Type   | Description   |
| ------------------------------------------ | ------ | ------------- |
| username<mark style="color:red;">\*</mark> | string | Username      |
| password<mark style="color:red;">\*</mark> | string | User password |

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

```
{
  "token": "r:qwertyuiop1234567890"
}
```

{% endtab %}
{% endtabs %}

### Delete Session

<mark style="color:green;">`POST`</mark> `https://api.ohmautomation.io/control/v1/logout`

This *endpoint* allows you to delete the session, making the token unusable.

**Headers**

| Name                                              | Type   | Description                 |
| ------------------------------------------------- | ------ | --------------------------- |
| X-Session-Token<mark style="color:red;">\*</mark> | string | Session token to be deleted |

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

```
{
  "token": <deleted_token>
}
```

{% endtab %}
{% endtabs %}

### Shortcuts JSON

<mark style="color:blue;">`GET`</mark> `https://api.ohmautomation.io/control/v1/shortcuts?token=abc`

This *endpoint* retrieves a *JSON* with the user’s shortcut configuration corresponding to the token.

**Query Parameters**

| Name                                    | Type   | Description   |
| --------------------------------------- | ------ | ------------- |
| token<mark style="color:red;">\*</mark> | string | Session token |

{% tabs %}
{% tab title="200 JSON with shortcut configuration" %}

```
{
    "shortcuts": [
        {
            "askConfirm": false,
            "category": "shortcut",
            "color": "#117ED9",
            "desc": "Turn off all lights",
            "icon": "house_2",
            "id": "abc123",
            "itemACL": [
                {
                    "id": "qwerty",
                    "read": true,
                    "write": true
                }
            ],
            "name": "Demo",
            "objectId": "system",
            "operations": [
                {
                    "function": {
                        "args": {},
                        "name": "turn_off_all_lights"
                    },
                    "objectId": "system",
                    "timer": {
                        "days": 0,
                        "hours": 0,
                        "min": 0,
                        "sec": 0
                    }
                }
            ],
            "parameters": []
        },
        {
            "askConfirm": false,
            "category": "shortcut",
            "color": "#FFB300",
            "desc": "Toggle TV",
            "icon": "tv",
            "id": "abc1234",
            "itemACL": [
                {
                    "id": "qwerty",
                    "read": true,
                    "write": true
                }
            ],
            "name": "TV",
            "objectId": "ac278aa6-fdd8-4899-960e-55ad702452ce",
            "operations": [
                {
                    "function": {
                        "args": {},
                        "name": "toggle"
                    },
                    "objectId": "ac278aa6-fdd8-4899-960e-55ad702452ce",
                    "timer": {
                        "days": 0,
                        "hours": 0,
                        "min": 0,
                        "sec": 0
                    }
                }
            ],
            "parameters": []
        },
        {
            "askConfirm": false,
            "category": "shortcut",
            "color": "#880E4F",
            "desc": "Open/Close gate",
            "icon": "gate",
            "id": "abc12345",
            "itemACL": [
                {
                    "id": "qwerty",
                    "read": true,
                    "write": true
                }
            ],
            "name": "Gate",
            "objectId": "",
            "operations": [
                {
                    "function": {
                        "args": {},
                        "name": "on"
                    },
                    "objectId": "a41f6a53-3b69-44e4-abf2-fed4bed8785c",
                    "timer": {
                        "days": 0,
                        "hours": 0,
                        "min": 0,
                        "sec": 0
                    }
                }
            ],
            "parameters": []
        }
    ]
}
```

{% endtab %}
{% endtabs %}

It is possible to avoid using the token in the URL by attaching it to the *Headers*.

### Shortcuts JSON with Headers

<mark style="color:blue;">`GET`</mark> `https://api.ohmautomation.io/control/v1/shortcuts`

As with the previous method, this also retrieves a *JSON* with the shortcut configuration, but the token is indicated in the *Headers*. We recommend this approach since it doesn't expose the token in the URL.

**Headers**

| Name                                              | Type   | Description        |
| ------------------------------------------------- | ------ | ------------------ |
| Content-Type                                      | string | `application/json` |
| X-Session-Token<mark style="color:red;">\*</mark> | string | Session token      |

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

```
{
    "shortcuts": [
        {
            "askConfirm": false,
            "category": "shortcut",
            "color": "#117ED9",
            "desc": "Turn off all lights",
            "icon": "house_2",
            "id": "abc123",
            "itemACL": [
                {
                    "id": "qwerty",
                    "read": true,
                    "write": true
                }
            ],
            "name": "Demo",
            "objectId": "system",
            "operations": [
                {
                    "function": {
                        "args": {},
                        "name": "turn_off_all_lights"
                    },
                    "objectId": "system",
                    "timer": {
                        "days": 0,
                        "hours": 0,
                        "min": 0,
                        "sec": 0
                    }
                }
            ],
            "parameters": []
        },
        {
            "askConfirm": false,
            "category": "shortcut",
            "color": "#FFB300",
            "desc": "Toggle TV",
            "icon": "tv",
            "id": "abc1234",
            "itemACL": [
                {
                    "id": "qwerty",
                    "read": true,
                    "write": true
                }
            ],
            "name": "TV",
            "objectId": "ac278aa6-fdd8-4899-960e-55ad702452ce",
            "operations": [
                {
                    "function": {
                        "args": {},
                        "name": "toggle"
                    },
                    "objectId": "ac278aa6-fdd8-4899-960e-55ad702452ce",
                    "timer": {
                        "days": 0,
                        "hours": 0,
                        "min": 0,
                        "sec": 0
                    }
                }
            ],
            "parameters": []
        },
        {
            "askConfirm": false,
            "category": "shortcut",
            "color": "#880E4F",
            "desc": "Open/Close gate",
            "icon": "gate",
            "id": "abc12345",
            "itemACL": [
                {
                    "id": "qwerty",
                    "read": true,
                    "write": true
                }
            ],
            "name": "Gate",
            "objectId": "",
            "operations": [
                {
                    "function": {
                        "args": {},
                        "name": "on"
                    },
                    "objectId": "a41f6a53-3b69-44e4-abf2-fed4bed8785c",
                    "timer": {
                        "days": 0,
                        "hours": 0,
                        "min": 0,
                        "sec": 0
                    }
                }
            ],
            "parameters": []
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### Execute Shortcut

<mark style="color:green;">`POST`</mark> `https://api.ohmautomation.io/control/v1/shortcut`

**Headers**

| Name                                              | Type   | Description        |
| ------------------------------------------------- | ------ | ------------------ |
| Content-Type                                      | string | `application/json` |
| X-Session-Token<mark style="color:red;">\*</mark> | string | Session token      |

**Request Body**

| Name                                      | Type   | Description |
| ----------------------------------------- | ------ | ----------- |
| id<mark style="color:red;">\*</mark>      | string | Shortcut ID |
| command<mark style="color:red;">\*</mark> | string | `run`       |

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

```
```

{% endtab %}
{% endtabs %}

### View Shortcut via Web

<mark style="color:blue;">`GET`</mark> `https://api.ohmautomation.io/control/v1/shortcut?token=abc&link=0&lang=it`

This *endpoint* allows viewing and executing a shortcut.

**Query Parameters**

| Name                                    | Type   | Description                        |
| --------------------------------------- | ------ | ---------------------------------- |
| token<mark style="color:red;">\*</mark> | string | Session token                      |
| id<mark style="color:red;">\*</mark>    | string | Shortcut ID                        |
| lang                                    | string | Display language (`en` by default) |

{% tabs %}
{% tab title="200 Web page for executing the shortcut" %}

```
HTML
```

{% 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://docs.ohmautomation.io/en/dev/apiv1.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.