HTTP API

All endpoints are reachable at:

https://api.cloud.iottly.com/v1.0/

All responses return JSON. POST and PUT requests that include a body must set Content-Type: application/json. Every call must include the bearer token header — see Iottly API Integration for how to obtain one.

Project Inspection

Get summary information about an Iottly project.

GET project/<PROJECT_ID>/inspect

Response 200:

{
  "id": "<project unique id>",
  "name": "<project name>",
  "projectgetagenturl": "<agent download url>",
  "agentfile": "<agent installer filename>",
  "agentapihost": "<project api hostname>",
  "board": "<device type, e.g. Linux ARMv5>"
}

Example:

curl -H 'Authentication: bearer <API_KEY>' \
  https://api.cloud.iottly.com/v1.0/project/<PROJECT_ID>/inspect

License Inspection

Get information about license tokens available in a project.

GET project/<PROJECT_ID>/license/[<LICENSE_ID>]

Omit <LICENSE_ID> to retrieve all licenses.

Response 200:

{
  "<license_token>": {
    "status": "paired",
    "board": {
      "macaddress": "02:43:3d:0a:07:1f",
      "operatingstatus": "connected",
      "id": "9af78306-384e-4dbc-9d63-af21cc5496a8",
      "name": "board 1"
    }
  },
  "<another_license_token>": { "status": "available", "board": {} }
}

Example:

curl -H 'Authentication: bearer <API_KEY>' \
  https://api.cloud.iottly.com/v1.0/project/<PROJECT_ID>/license

Device Properties

List all devices

GET project/<PROJECT_ID>/devices/props

Response 200:

{
  "count": 3,
  "errors": null,
  "devices": [
    {
      "macaddress": "<MAC address>",
      "name": "<device name>",
      "operatingstatus": "connected",
      "token": "<license token>",
      "agent_version": "<agent version>",
      "ID": "<device unique ID>"
    }
  ]
}

Single device

GET project/<PROJECT_ID>/device/<DEVICE_ID>/props

Edit device name

PUT project/<PROJECT_ID>/device/<DEVICE_ID>/props

curl -X PUT \
  -H 'Authentication: bearer <API_KEY>' \
  -H 'Content-type: application/json' \
  --data '{"name": "my-sensor-01"}' \
  https://api.cloud.iottly.com/v1.0/project/<PROJECT_ID>/device/<DEVICE_ID>/props

Command API

Send a command to a device. The command type must match a message type declared in the project.

POST /project/<PROJECT_ID>/device/<DEVICE_ID>/command

Request body:

{
  "cmd_type": "read_sensor_data",
  "values": {
    "read_sensor_data.sensortype": "temperature"
  }
}

Note: Each key in values must be prefixed with the command type followed by a dot: <cmd_type>.<parameter>.

Example:

curl -H 'Authentication: bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{"cmd_type": "echo", "values": {"echo.content": "hello!"}}' \
  https://api.cloud.iottly.com/v1.0/project/<PROJECT_ID>/device/<DEVICE_ID>/command

Message History

Get messages sent by a device (newest to oldest).

GET project/<PROJECT_ID>/messages/<DEVICE_ID>

Query parameters:

Response 200:

{
  "status": 200,
  "messages": [
    {
      "from": "3781de91-d446-4c64-825d-756dd60f2dab",
      "timestamp": { "$date": "2017-09-20T00:33:27.230Z" },
      "type": "userdefined",
      "payload": { "sensor_data_reading": { "temperature": 37.4 } }
    }
  ]
}

Message fields:

Example:

curl -H 'Authentication: bearer <API_KEY>' \
  https://api.cloud.iottly.com/v1.0/project/<PROJECT_ID>/messages/<DEVICE_ID>

Paginated Messages

Retrieve messages page by page with optional time-range filtering.

GET project/<PROJECT_ID>/device/<DEVICE_ID>/messages/paginated

Query parameters:

HTTP status codes

API Overview

Iottly exposes two complementary APIs for backend integration:

All API endpoints require a valid API key issued from the dashboard under Settings → API Keys.

Base URL

https://api.cloud.iottly.com/v1

Authentication

Pass your API key as a bearer token in every request:

Authorization: Bearer ik_live_xxxxxxxxxxxxxxxxxxxx

API keys are project-scoped. A key created in project A cannot access devices in project B.

Rate limits

Responses include standard rate-limit headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1746537600

When the limit is exceeded the API responds with 429 Too Many Requests. Implement exponential back-off before retrying.

Common REST endpoints

List devices

GET /v1/devices

{
  "data": [
    {
      "id": "dev_01j3k...",
      "name": "gateway-milan-01",
      "project_id": "prj_...",
      "status": "online",
      "last_seen_at": "2026-05-06T14:22:00Z"
    }
  ],
  "meta": { "total": 42, "page": 1, "per_page": 20 }
}

Get a single device

GET /v1/devices/:id

Send a command

POST /v1/devices/:id/commands
Content-Type: application/json

{
  "command": "uptime",
  "timeout_s": 10
}

{
  "command_id": "cmd_...",
  "status": "pending"
}

Get command result

GET /v1/commands/:command_id

{
  "command_id": "cmd_...",
  "status": "completed",
  "exit_code": 0,
  "stdout": " 14:22:45 up 12 days,  3:11,  0 users,  load average: 0.02",
  "stderr": "",
  "completed_at": "2026-05-06T14:22:46Z"
}

Error format

All errors follow the same shape:

{
  "error": {
    "code": "device_offline",
    "message": "The device is not currently connected.",
    "request_id": "req_..."
  }
}

Next steps

• WebSocket API — real-time telemetry and command streaming