HTTP Requests Tool — Complete Guide

The HTTP Requests tool turns your dashboard into a built-in API client — like a mini Postman that lives inside Virtuino Cloud. You can call any public REST API, test it live, and then have the server run it automatically (on a schedule or when a field changes) and feed the response straight into your fields and scripts.

Contents

1. Anatomy of a request

Every request you build has the same top section, regardless of the tabs you fill in:

Below the URL there are four tabs that shape the request: Params, Authorization, Headers and Body. The second top-level tab, automation, is covered in section 7.

2. Params tab

Query parameters are the ?key=value&key2=value2 part of a URL. Instead of typing them by hand, add them as rows here — each enabled row is appended to the URL, correctly URL-encoded.

{
  "args": {
    "city": "Athens",
    "units": "metric"
  },
  "url": "https://httpbin.org/get?city=Athens&units=metric"
}

3. Authorization tab

Many APIs require credentials. Choose the type and the tool builds the correct header for you. The credentials are stored with the request and sent on every (manual or automatic) run.

3a. No Auth

The default. Nothing is added. Use it for open APIs like Open-Meteo.

3b. Bearer Token

Adds the header Authorization: Bearer <token>. This is the most common scheme for modern APIs (OAuth2, personal access tokens, etc.).

{
  "authenticated": true,
  "token": "my-secret-123"
}

3c. Basic Auth

Adds Authorization: Basic <base64(username:password)>. The tool does the Base64 encoding for you.

{
  "authenticated": true,
  "user": "admin"
}

3d. API Key

Sends a custom header of your choice, e.g. X-API-Key: <value>. Set the header name and the value. Many weather/finance APIs use this style.

{
  "headers": {
    "Host": "httpbin.org",
    "X-Api-Key": "abc123"
  }
}

4. Headers tab

Custom request headers, added as key/value rows (same layout as Params). Use them for content negotiation, custom tokens, or anything the API documents. Common examples:

{
  "headers": {
    "Accept": "application/json",
    "X-Demo": "virtuino",
    "Host": "httpbin.org"
  }
}

5. Body tab

The body is the payload you send to the server. It only applies to POST, PUT and PATCH — for GET/DELETE it is ignored. Choose one of four modes:

{
  "device": "pump-1",
  "command": "on",
  "value": 42
}

{
  "json": { "device": "pump-1", "command": "on", "value": 42 },
  "headers": { "Content-Type": "application/json" }
}

{
  "form": { "relay": "1", "duration": "30" }
}

6. The Test button & reading results

The Test button sends the request immediately through the Virtuino server (never from your browser — that avoids CORS problems and applies our security checks). The results panel shows:

• ● 200 OK — a colored status badge. Green = success (2xx), amber = redirect (3xx), red = error (4xx/5xx).
• The full response body, pretty-printed if it is JSON.

Logs — what happened on the automatic runs

The logs button at the bottom of the editor shows the last 5 automatic runs (polling or trigger — not tests): when, how long it took, the status code or error, and the start of the response (up to 4000 characters). It is the first place to look when a saved request does not seem to do anything.

7. Automation

Switch to the automation tab to make the request run by itself on the server. There are three independent cards — enable any combination with the checkbox at the top of each.

7a. Polling

Runs the request on a fixed schedule. Set the interval in minutes (1–1440, i.e. up to 24 hours). The server executes the request every interval and — if Store output is on — saves the response to your field.

7b. Trigger

Runs the request when one of your fields meets a condition. Pick a field, a condition, and a value:

• 10-second cooldown. A request never runs twice within 10 seconds (polling and trigger together). A trigger that comes sooner is skipped, not postponed — for a comparison condition that event is used up until the condition becomes false and true again.
• What does not trigger a request: values written by a rule, and values that arrived over HTTP — through the HTTP API or as the stored response of another HTTP Request. This keeps requests from calling each other in a loop. Values from boards over MQTT, dashboards, schedulers, scripts and the JSON Splitter do trigger.
• changed after a server restart: the first value only sets the starting point; the next different value fires.

7c. Store output

Pick the field where the raw response is written after each run (polling or trigger):

• Only successful responses are stored — status 200–299. An error (401, 404, 500…) or a timeout leaves the field untouched, with its last good value; the logs show what went wrong.
• The response is stored as text, with the time of the run. A JSON response is stored as JSON text.
• It is not sent via MQTT, and it does not start other HTTP Requests. It does start scripts and rules, and the JSON Splitter — which is how you get the numbers out.

8. Worked example A — Weather into fields, no code

Goal: fetch the current temperature, humidity and wind for Athens every 15 minutes and keep each in its own field, with history — using only the HTTP Request and a JSON Splitter.

Step 1 — Create the fields

In Console → Fields create:

• weather/raw — standard (non-historical): receives the whole response.
• weather/temperature, weather/humidity, weather/wind — historical: one number each, with history.

Step 2 — Build & test the request

GET   https://api.open-meteo.com/v1/forecast?latitude=37.98&longitude=23.73&current=temperature_2m,relative_humidity_2m,wind_speed_10m

(Equivalently, put the URL up to /forecast and add latitude, longitude, current in the Params tab.) Press Test — you should get something like:

{
  "latitude": 37.98,
  "longitude": 23.72,
  "current": {
    "time": "2026-06-20T10:00",
    "interval": 900,
    "temperature_2m": 27.8,
    "relative_humidity_2m": 41,
    "wind_speed_10m": 12.6
  }
}

Step 3 — Automation

• Polling: enable, interval 15 minutes. Open-Meteo updates its current values every 15 minutes ("interval": 900 seconds), so polling more often only repeats the same numbers.
• Store output: enable → field weather/raw. Save.

Step 4 — The JSON Splitter

In the dashboard, Tools → JSON Splitter → new splitter. Source field weather/raw, leave time path empty, and add three rows:

That's the whole pipeline: request → weather/raw → JSON Splitter → three fields, every 15 minutes. Put the three fields on widgets, or add a rule on weather/wind to be warned of strong wind.

9. Worked example B — The same with a script

Use a script instead of the JSON Splitter when you need more than copying numbers: a conversion, a condition, a calculated value. Steps 1–3 stay the same.

Step 4 — The script

Tools → Scripts → add script, then map the fields:

let data;
try {
    data = JSON.parse(inputs.raw.value);
} catch (e) {
    return;                                  // not JSON yet
}
const cur = data.current || {};
if (typeof cur.temperature_2m === 'number')       outputs.temperature = cur.temperature_2m;
if (typeof cur.relative_humidity_2m === 'number') outputs.humidity    = cur.relative_humidity_2m;
if (typeof cur.wind_speed_10m === 'number')       outputs.wind        = cur.wind_speed_10m;

A value that is missing from the response is simply not written, so its field keeps its last value. Extend the code as you need — for example write wind in Beaufort instead of km/h. See the Scripts guide for everything a script can do.

10. Security & limits

Time limits

Size limits

Security

• SSRF protection: only http/https URLs are allowed, and the hostname is DNS-resolved and checked — requests to private/loopback ranges (127.x, 10.x, 192.168.x, 169.254.x, 172.16–31.x, ::1) are rejected. You cannot use this tool to reach internal infrastructure.
• TLS verified: HTTPS certificates are validated (self-signed/invalid certs are refused).
• Redirects: up to 5 are followed.
• Server-side execution: every run (Test, polling, trigger) happens on the Virtuino server, so your credentials are never exposed to the browser and there are no CORS restrictions.

11. Troubleshooting & FAQ

The list shows small icons next to a request — what are they?

polling enabled  ·  trigger enabled  ·  stores output to a field.

Test works, but nothing happens automatically.

Open the logs of the request first — they show every automatic run and its result. Then check that (1) the relevant card's checkbox in the automation tab is on and the request is saved; (2) for Store output, a field is selected; (3) for triggers, the field really updates, the condition is met, and the value does not come from a rule or over HTTP (7b).

The output field keeps an old value.

Only successful responses (200–299) are stored. If the API answers with an error, the field keeps its last good value — the logs show the status code and the error message.

My script or JSON Splitter never runs after the response is stored.

The script's input — or the splitter's source — must be the same field chosen in Store output, and for a script that input must have trg ticked. The script's icon must be green (active and complete mapping) — see Scripts — troubleshooting.

The output field is empty or a value is rejected.

The output field is historical. Historical fields take at most 512 characters, so a JSON response is rejected — use a standard field for the raw response.

How do I send the API key as a query parameter instead of a header?

Leave Authorization on No Auth and add the key as a row in the Params tab (e.g. apikey = ...).

Virtuino Cloud — HTTP Requests Tool