HTTP API

Tutti gli endpoint sono raggiungibili a:

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

Tutte le risposte restituiscono JSON. Le richieste POST e PUT che includono un body devono impostare Content-Type: application/json. Ogni chiamata deve includere l’header con il bearer token — vedi Iottly API Integration per come ottenerne uno.

Ispezione progetto

Ottieni informazioni riepilogative su un progetto Iottly.

GET project/<PROJECT_ID>/inspect

Risposta 200:

{
  "id": "<id univoco del progetto>",
  "name": "<nome del progetto>",
  "projectgetagenturl": "<url download agent>",
  "agentfile": "<nome file installer agent>",
  "agentapihost": "<hostname api del progetto>",
  "board": "<tipo device, es. Linux ARMv5>"
}

Esempio:

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

Ispezione licenze

Ottieni informazioni sui token di licenza disponibili nel progetto.

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

Ometti <LICENSE_ID> per recuperare tutte le licenze.

Risposta 200:

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

Esempio:

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

Proprietà device

Tutti i device

GET project/<PROJECT_ID>/devices/props

Risposta 200:

{
  "count": 3,
  "errors": null,
  "devices": [
    {
      "macaddress": "<indirizzo MAC>",
      "name": "<nome device>",
      "operatingstatus": "connected",
      "token": "<token licenza>",
      "agent_version": "<versione agent>",
      "ID": "<ID univoco device>"
    }
  ]
}

Singolo device

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

Modifica nome device

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

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

Command API

Invia un comando a un device. Il tipo di comando deve corrispondere a un tipo di messaggio dichiarato nel progetto.

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

Body della richiesta:

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

Nota: Ogni chiave in values deve essere preceduta dal tipo di comando seguito da un punto: <cmd_type>.<parametro>.

Esempio:

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

Cronologia messaggi

Ottieni i messaggi inviati da un device (dal più recente al meno recente).

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

Parametri query:

Risposta 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 } }
    }
  ]
}

Campi del messaggio:

Esempio:

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

Messaggi paginati

Recupera i messaggi pagina per pagina con filtro opzionale su intervallo temporale.

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

Parametri query:

Codici HTTP di risposta

Panoramica API

Iottly espone due API complementari per l’integrazione backend:

Tutti gli endpoint API richiedono una API key valida, generabile dalla dashboard in Impostazioni → API Key.

URL di base

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

Autenticazione

Passa la tua API key come bearer token in ogni richiesta:

Authorization: Bearer ik_live_xxxxxxxxxxxxxxxxxxxx

Le API key sono scoped al progetto. Una key creata nel progetto A non può accedere ai device del progetto B.

Limiti di frequenza

Le risposte includono gli header standard per i rate limit:

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

Quando il limite viene superato l’API risponde con 429 Too Many Requests. Implementa un back-off esponenziale prima di riprovare.

Endpoint REST principali

Lista device

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 }
}

Dettaglio singolo device

GET /v1/devices/:id

Invia un comando

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

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

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

Risultato del comando

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"
}

Formato degli errori

Tutti gli errori seguono la stessa struttura:

{
  "error": {
    "code": "device_offline",
    "message": "Il device non è attualmente connesso.",
    "request_id": "req_..."
  }
}

Prossimi passi

• WebSocket API — telemetria e comandi in streaming real-time