HTTP REST API Guide

// Required libraries — install via Arduino IDE → Library Manager:
//   ArduinoJson  (by Benoit Blanchon)
// Board support: Arduino IDE → File → Preferences → Additional boards manager URLs:
//   https://arduino.esp8266.com/stable/package_esp8266com_index.json
// Then: Tools → Board → Boards Manager → "esp8266 by ESP8266 Community" → install/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 → Keys & Sub Users
const char* writeUrl   = "https://api.virtuino.com/api/data/write";
const char* historyUrl = "https://api.virtuino.com/api/data/path-history/esp8266?latest=true";
// historyUrl returns the latest value of every field whose name starts with "esp8266/".

// 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 — "path" is joined to each "field" with a / — together they must match a field name in the Console
    StaticJsonDocument<256> doc;
    doc["api_key"]   = apiKey;
    doc["client_id"] = "esp8266-01";   // optional: names this board in My Virtuino World
    doc["path"]      = "esp8266";    // esp8266/temperature, esp8266/humidity
    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) + " " + http.getString());  // 200 = success; the reply lists any field that does not exist
    http.end();
}

// ── Read the latest value of every field under the path ───────────────
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<1024> 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 → Keys & Sub Users
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 — "path" is joined to each "field" with a / — together they must match a field name in the Console
    StaticJsonDocument<256> doc;
    doc["api_key"]   = apiKey;
    doc["client_id"] = "uno-01";   // optional: names this board in My Virtuino World
    doc["path"]      = "arduino_uno";   // arduino_uno/temperature, arduino_uno/humidity
    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();
    String reply = http.responseBody();  // always read the reply before the next request
    Serial.println("Write → HTTP " + String(code) + " " + reply);  // 200 = success; the reply lists any field that does not exist
}

// ── Read the latest value of every field under the path ───────────────
void readLatest() {
    // Simplest with ArduinoHttpClient: pass the API key as a query parameter
    String path = String("/api/data/path-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<1024> doc;
    if (deserializeJson(doc, payload)) { Serial.println("JSON parse error"); return; }
    JsonArray fields = doc["fields"];
    for (JsonObject f : fields) {  // Serial.printf does not exist on these boards
        Serial.print("  "); Serial.print((const char*)f["field"]);
        Serial.print(" = "); Serial.println((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 → Keys & Sub Users
BASE_URL = "https://api.virtuino.com/api/data"
PATH     = "esp32"          # joined to each field name: esp32/temperature, esp32/humidity

# ── 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,
    "client_id": "python-script",  # optional
    "path":      PATH,
    "data": [
        { "field": "temperature", "value": 23.75, "publish": True },
        { "field": "humidity",    "value": 61.2,  "publish": True }
    ]
})
print("Write:", r.json())  # {"success": true, "count": 2, "total": 2, "fields": ["esp32/temperature", "esp32/humidity"], ...}

# ── Read the latest value of every field under the path ───────────────
# Returns {"success": true, "path": "esp32", "fields": [{"field": "esp32/temperature", "value": ..., "time": ...}, ...]}
r = requests.get(f"{BASE_URL}/path-history/{PATH}",
                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}/field/{PATH}/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 → Keys & Sub Users
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,
            path: "esp32",  // joined to each field name with a /
            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, count: 2, total: 2, fields: ["esp32/temperature", "esp32/humidity"], ...}
}

// ── Read the latest value of every field under the path ───────────────
// For GET requests, pass the API key as a query parameter
async function readLatest() {
    const res = await fetch(`${BASE_URL}/path-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; "path" + "/" + "field" must match a field name in 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 '{
       "path": "esp32",
       "data": [
         {"field":"temperature","value":23.75,"publish":true},
         {"field":"humidity","value":61.2,"publish":true}
       ]
     }'

# ── Read the latest value of every field under the path ───────────────
# For GET requests, pass the API key as a query parameter
curl "https://api.virtuino.com/api/data/path-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/field/esp32/temperature?api_key=YOUR_API_KEY&from=2026-06-12T00:00:00Z&to=2026-06-12T23:59:59Z&limit=15"

# ── List all fields ──────────────────────────────────────────────────
# Returns every field of the account with its latest value and time
curl "https://api.virtuino.com/api/data/fields?api_key=YOUR_API_KEY"