HTTP REST API Guide

// Required libraries — install via Arduino IDE → Library Manager:
//   ArduinoJson  (by Benoit Blanchon)
// Board support: "esp8266 by ESP8266 Community" — Boards Manager → update to version 3.x
// setInsecure() requires ESP8266 core ≥ 2.5.0. If you get a compile error, update the board package.
// ESP8266WiFi, ESP8266HTTPClient, and WiFiClientSecure are part of the ESP8266 core — no separate install needed.
#include <ESP8266WiFi.h>
#include <ESP8266HTTPClient.h>
#include <WiFiClientSecure.h>  // required for HTTPS on ESP8266 — ESP32 handles it natively
#include <ArduinoJson.h>

// ── Configuration — replace with your own values ─────────────────────
const char* ssid       = "YOUR_WIFI_SSID";
const char* password   = "YOUR_WIFI_PASSWORD";
const char* apiKey     = "YOUR_API_KEY";       // Console → API & Connections
const char* writeUrl   = "https://api.virtuino.com/api/data/write";
const char* historyUrl = "https://api.virtuino.com/api/data/device-history/esp8266?latest=true";
// Change "esp8266" in historyUrl to match your device name in the Console.

// ESP8266 needs a WiFiClientSecure object passed to http.begin() for HTTPS
WiFiClientSecure client;

// ── Send two sensor readings to the platform ──────────────────────────
void writeData(float temp, float hum) {
    if (WiFi.status() != WL_CONNECTED) return;
    client.setInsecure();  // skip TLS certificate verification — simplest setup for IoT
    HTTPClient http;
    http.begin(client, writeUrl);  // ESP8266 requires the client object; ESP32 does not
    http.addHeader("Content-Type", "application/json");
    // Build JSON body — "device_name" must match the device created in the Console
    StaticJsonDocument<256> doc;
    doc["api_key"]     = apiKey;
    doc["device_name"] = "esp8266";
    JsonArray data = doc.createNestedArray("data");
    JsonObject f1 = data.createNestedObject();
    f1["field"] = "temperature"; f1["value"] = temp; f1["publish"] = true;  // publish:true also sends to MQTT
    JsonObject f2 = data.createNestedObject();
    f2["field"] = "humidity"; f2["value"] = hum; f2["publish"] = true;
    String body;
    serializeJson(doc, body);
    int code = http.POST(body);
    Serial.println("Write → HTTP " + String(code));  // 200 = success
    http.end();
}

// ── Read the latest values stored for this device ─────────────────────
void readLatest() {
    if (WiFi.status() != WL_CONNECTED) return;
    client.setInsecure();
    HTTPClient http;
    http.begin(client, historyUrl);
    http.addHeader("x-api-key", apiKey);  // pass API key as header for GET requests
    int code = http.GET();
    String payload = http.getString();
    http.end();
    Serial.println("Read → HTTP " + String(code));
    if (code != 200) {
        Serial.println("Error: " + payload);  // print server error message
        return;
    }
    // Parse the JSON response
    StaticJsonDocument<512> doc;
    DeserializationError err = deserializeJson(doc, payload);
    if (err) { Serial.println("JSON parse error: " + String(err.c_str())); return; }
    // Iterate the "fields" array and print each name/value pair
    JsonArray fields = doc["fields"];
    for (JsonObject f : fields) {
        const char* name  = f["field"];
        const char* value = f["value"];
        Serial.printf("  %s = %s\n", name, value);
    }
}

void setup() {
    Serial.begin(115200);
    WiFi.begin(ssid, password);
    while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); }
    Serial.println("\nWi-Fi connected");
}

void loop() {
    static unsigned long last = 0;
    if (millis() - last > 15000) {  // send every 15 seconds
        last = millis();
        writeData(random(200, 300) / 10.0f, random(400, 700) / 10.0f);
        readLatest();
    }
}

// Required libraries — install via Arduino IDE → Library Manager:
//   WiFiNINA  (by Arduino)
//   ArduinoHttpClient  (by Arduino)
//   ArduinoJson  (by Benoit Blanchon)
// Compatible boards: Arduino Uno WiFi Rev2, Arduino MKR WiFi 1010
#include <WiFiNINA.h>
#include <ArduinoHttpClient.h>
#include <ArduinoJson.h>

// ── Configuration — replace with your own values ─────────────────────
const char* ssid     = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";
const char* apiKey   = "YOUR_API_KEY";        // Console → API & Connections
const char* server   = "api.virtuino.com";    // hostname only — port/path set below

// WiFiSSLClient handles TLS; HttpClient wraps it with the hostname and port
WiFiSSLClient   wifiClient;
HttpClient      http(wifiClient, server, 443);

// ── Send two sensor readings to the platform ──────────────────────────
void writeData(float temp, float hum) {
    // Build JSON body — "device_name" must match the device created in the Console
    StaticJsonDocument<256> doc;
    doc["api_key"]     = apiKey;
    doc["device_name"] = "arduino_uno";
    JsonArray data = doc.createNestedArray("data");
    JsonObject f1 = data.createNestedObject();
    f1["field"] = "temperature"; f1["value"] = temp; f1["publish"] = true;  // publish:true also sends to MQTT
    JsonObject f2 = data.createNestedObject();
    f2["field"] = "humidity"; f2["value"] = hum; f2["publish"] = true;
    String body;
    serializeJson(doc, body);
    // ArduinoHttpClient requires an explicit beginRequest/endRequest sequence
    http.beginRequest();
    http.post("/api/data/write");
    http.sendHeader("Content-Type", "application/json");
    http.sendHeader("Content-Length", body.length());
    http.endRequest();
    http.print(body);
    int code = http.responseStatusCode();
    Serial.println("Write → HTTP " + String(code));  // 200 = success
}

// ── Read the latest values stored for this device ─────────────────────
void readLatest() {
    // Pass API key as a query parameter — ArduinoHttpClient does not support custom GET headers
    String path = String("/api/data/device-history/arduino_uno?api_key=") + apiKey + "&latest=true";
    http.get(path);
    int code = http.responseStatusCode();
    String payload = http.responseBody();
    Serial.println("Read → HTTP " + String(code));
    if (code != 200) { Serial.println("Error: " + payload); return; }
    // Parse JSON and print each field/value pair
    StaticJsonDocument<512> doc;
    if (deserializeJson(doc, payload)) { Serial.println("JSON parse error"); return; }
    JsonArray fields = doc["fields"];
    for (JsonObject f : fields)
        Serial.printf("  %s = %s\n", (const char*)f["field"], (const char*)f["value"]);
}

void setup() {
    Serial.begin(9600);
    while (!Serial);  // wait for Serial Monitor to open (needed on Uno WiFi Rev2)
    while (WiFi.begin(ssid, password) != WL_CONNECTED) { delay(1000); }
    Serial.println("Wi-Fi connected");
}

void loop() {
    static unsigned long last = 0;
    if (millis() - last > 15000) {  // send every 15 seconds
        last = millis();
        writeData(random(200, 300) / 10.0f, random(400, 700) / 10.0f);
        readLatest();
    }
}

# pip install requests
import requests

# ── Configuration — replace with your own values ──────────────────────
API_KEY  = "YOUR_API_KEY"   # Console → API & Connections
BASE_URL = "https://api.virtuino.com/api/data"
DEVICE   = "esp32"          # must match a device name created in the Console

# ── Write two fields ──────────────────────────────────────────────────
# publish:True also pushes the value to the MQTT broker (Essential+ plan)
r = requests.post(f"{BASE_URL}/write", json={
    "api_key":     API_KEY,
    "device_name": DEVICE,
    "data": [
        { "field": "temperature", "value": 23.75, "publish": True },
        { "field": "humidity",    "value": 61.2,  "publish": True }
    ]
})
print("Write:", r.json())  # {"success": true, "message": "Stored 2 fields ..."}

# ── Read latest snapshot for all fields of a device ───────────────────
# Returns {"success": true, "device": ..., "fields": [{"field": ..., "value": ...}, ...]}
r = requests.get(f"{BASE_URL}/device-history/{DEVICE}",
                params={ "api_key": API_KEY, "latest": "true" })
print("Latest:", r.json())

# ── Read last 15 records for one field in a time range ────────────────
# Timestamps must be in ISO 8601 UTC format: YYYY-MM-DDTHH:MM:SSZ
r = requests.get(f"{BASE_URL}/device/{DEVICE}/field/temperature", params={
    "api_key": API_KEY,
    "from":    "2026-06-12T00:00:00Z",
    "to":      "2026-06-12T23:59:59Z",
    "limit":   15
})
print("History:", r.json())

// ── Configuration — replace with your own values ─────────────────────
const API_KEY  = "YOUR_API_KEY";   // Console → API & Connections
const BASE_URL = "https://api.virtuino.com/api/data";

// ── Write two fields ──────────────────────────────────────────────────
// api_key goes in the JSON body for POST requests
async function writeData() {
    const res = await fetch(`${BASE_URL}/write`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            api_key: API_KEY,
            device_name: "esp32",  // must match a device created in the Console
            data: [
                { field: "temperature", value: 23.75, publish: true },  // publish:true also sends to MQTT
                { field: "humidity",    value: 61.2,  publish: true }
            ]
        })
    });
    const data = await res.json();
    console.log("Write:", data);  // {success: true, message: "Stored 2 fields ..."}
}

// ── Read latest snapshot for all fields of a device ───────────────────
// For GET requests, pass the API key as a query parameter
async function readLatest() {
    const res = await fetch(`${BASE_URL}/device-history/esp32?api_key=${API_KEY}&latest=true`);
    const data = await res.json();
    console.log("Latest:", data);
    // Access individual fields: data.fields[0].value, data.fields[1].value, etc.
}

writeData();
readLatest();

# ── Write two fields ──────────────────────────────────────────────────
# API key goes in the x-api-key header for POST; "device_name" must match the Console
# publish:true also pushes the value to the MQTT broker (Essential+ plan)
curl -X POST https://api.virtuino.com/api/data/write \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "device_name": "esp32",
       "data": [
         {"field":"temperature","value":23.75,"publish":true},
         {"field":"humidity","value":61.2,"publish":true}
       ]
     }'

# ── Read latest snapshot for all fields of a device ───────────────────
# For GET requests, pass the API key as a query parameter
curl "https://api.virtuino.com/api/data/device-history/esp32?api_key=YOUR_API_KEY&latest=true"

# ── Read last 15 temperature records in a time range ─────────────────
# Timestamps in ISO 8601 UTC: YYYY-MM-DDTHH:MM:SSZ
curl "https://api.virtuino.com/api/data/device/esp32/field/temperature?api_key=YOUR_API_KEY&from=2026-06-12T00:00:00Z&to=2026-06-12T23:59:59Z&limit=15"

# ── Get full account inventory ────────────────────────────────────────
# Returns all devices, their online status, last-seen time, and available fields
curl "https://api.virtuino.com/api/data/device-info?api_key=YOUR_API_KEY"