<commit_before>---
title: Iottly developer documentation - API reference
---

# API reference

All the APIs endpoint described in this document are reachable at:

```
api.cloud.iottly.com/v1.0/
```

All the API endpoints return json data in the response body.
POST and PUT request may send a json payload when required by the API, in this case
the caller should provide a `Content-Type: application/json` header.

> __Note:__ Remember that all the calls to the iottly API MUST BE authenticated using the procedure described [here]({{'dev/api/basics#api-authentication' | relative_url}})

__Table of content__
>- **[Project inspection API](#project-inspection-api)**
>- **[Command API](#command-api)**
>- **[Message history API](#message-history-api)**


## Project inspection API

Get summary information about a __iottly project__

__GET__ `project/<PROJECT ID>/inspect`

### Response

- **200** OK
  - the response body will contain information on the specific project
  ```json
  {
    "id": "58f73b41c3cc4800078010c5",
    "name": "My awesome project",
    "deployment_groups": [
      {
        "status": "",
        "boards": [
            "a2792ce8-216f-477c-a5cc-4f7e9f407e29"
        ],
        "branch": "",
        "name": "_orphaned",
        "fwcode": {
            "codesections": [],
            "snippets": []
        },
        "current_revision": "",
        "id": "1fef341c-2b1d-42d3-ac9a-2da8d4ec4756"
      }
    ]
  }
  ```
- **401** Unauthorized - Client is not authenticated
- **403** Forbidden - Client does not have permission for the specified project or device
- **500** Server Error

### Example request
```shell
curl -H 'Authentication: bearer <API KEY>' https://api.cloud.iottly.com/v1.0/project/<PROJECT ID>/inspect
```


## Command API
Send a command to a device

__POST__ `/project/<PROJECT ID>/device/<DEVICE ID>/command`

### Request body

The endpoint takes a json formatted object with the keys:

- **cmd_type**: the command type (must be a message type declared in the project)
- **values**: an object containing the comamand options (the format is specific for each command, you can find the format for each command in the __console__ panel of the iottly web interface)

> __Example request payload__
```
{
    "cmd_type": "echo",
    "values": {
        "echo.content": "hi there!"
    }
}
```
>
> __ATTENTION:__ Please note that each command option key in the values object should be prefixed by the command type followed by a dot.

### Response

- **200** OK
- **400** Client submitted invalid data, see error key in the response<commit_msg>API: add license inspection doc<commit_after>---
title: Iottly developer documentation - API reference
---

# API reference

All the APIs endpoint described in this document are reachable at:

```
api.cloud.iottly.com/v1.0/
```

All the API endpoints return json data in the response body.
POST and PUT request may send a json payload when required by the API, in this case
the caller should provide a `Content-Type: application/json` header.

> __Note:__ Remember that all the calls to the iottly API MUST BE authenticated using the procedure described [here]({{'dev/api/basics#api-authentication' | relative_url}})

__Table of content__
>- **[Project inspection API](#project-inspection-api)**
>- **[License inspection API](#license-inspection-api)**
>- **[Command API](#command-api)**
>- **[Message history API](#message-history-api)**


## Project inspection API

Get summary information about a __iottly project__

__GET__ `project/<PROJECT ID>/inspect`

### Response

- **200** OK
  - the response body will contain information on the specific project
  ```json
  {
    "id": "58f73b41c3cc4800078010c5",
    "name": "My awesome project",
    "deployment_groups": [
      {
        "status": "",
        "boards": [
            "a2792ce8-216f-477c-a5cc-4f7e9f407e29"
        ],
        "branch": "",
        "name": "_orphaned",
        "fwcode": {
            "codesections": [],
            "snippets": []
        },
        "current_revision": "",
        "id": "1fef341c-2b1d-42d3-ac9a-2da8d4ec4756"
      }
    ]
  }
  ```
- **401** Unauthorized - Client is not authenticated
- **403** Forbidden - Client does not have permission for the specified project
- **500** Server Error

### Example request
```shell
curl -H 'Authentication: bearer <API KEY>' https://api.cloud.iottly.com/v1.0/project/<PROJECT ID>/inspect
```


## License inspection API

Get summary information about the __license tokens__ available in your __iottly project__

__GET__ `project/<PROJECT ID>/license/[<LICENSE_ID>]`

### Response


- **200** OK
  - the response body will contain information on the specific license or on all the licenses available
  ```json
  {
    "599f8661ae4efc9ab47ebfe76013bbae": {
      "status": "paired",
      "board": {
        "macaddress": "02:43:3d:0a:07:1f",
        "operatingstatus": "connected",
        "id": "9af78306-384e-4dbc-9d63-af21cc5496a8",
        "name": "board 1"
      }
    },
    "c11b659250ccf128e0bfee34f1b1ef64": {
      "status": "available",
      "board": {}
    },
    "1e01b0ae1820d23ec3bc246fda3f3a90": {
      "status": "available",
      "board": {}
    },
    "87adcfb4d719a0d1c86fdd1de07fed95": {
      "status": "available",
      "board": {}
    },
    "5f3b2ec15843943e873c0df2e919f7d9": {
      "status": "available",
      "board": {}
    }
  }
  ```
  - **401** Unauthorized - Client is not authenticated
  - **403** Forbidden - Client does not have permission for the specified project
  - **500** Server Error

### Example request
```shell
curl -H 'Authentication: bearer <API KEY>' https://api.cloud.iottly.com/v1.0/project/<PROJECT ID>/license
```

## Command API
Send a command to a device

__POST__ `/project/<PROJECT ID>/device/<DEVICE ID>/command`

### Request body

The endpoint takes a json formatted object with the keys:

- **cmd_type**: the command type (must be a message type declared in the project)
- **values**: an object containing the comamand options (the format is specific for each command, you can find the format for each command in the __console__ panel of the iottly web interface)

> __Example request payload__
```
{
    "cmd_type": "echo",
    "values": {
        "echo.content": "hi there!"
    }
}
```
>
> __ATTENTION:__ Please note that each command option key in the values object should be prefixed by the command type followed by a dot.

### Response

- **200** OK
- **400** Client submitted invalid data, see error key in the response
{'fraction_non_alphanumeric': 0.12916602672400554, 'fraction_numerical': 0.043925664260482264, 'mean_word_length': 3.347129506008011, 'pattern_counts': {'":': 49, '<': 17, '<?xml version=': 0, '>': 32, 'https://': 3, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3354107', 'n_tokens_mistral': 2201, 'n_tokens_neox': 2014, 'n_words': 662}