REST API Call

The REST API Call operation sends an HTTP/HTTPS request to an external URL and exposes the response status code, headers, and body as outputs. It is a dual-role action+trigger: as a leaf in the caller’s path it issues the request asynchronously and returns immediately; when the response arrives, it populates the outputs and fires the downstream trigger path.

Paid plan required

Egress operations (REST API Call, Webhook) are not available on the Free tier. They require a Plus or Pro plan.

With URL empty and the URL input unconnected every request fails, and the Editor shows a warning ring on the URL input saying so.

Inputs

Port	Type	Required	Description
> (Gate)	Any	No	When connected, a false or Nil value stops the path. See Gate Inputs.
URL	String	No	Overrides the URL property when connected.
Body	Any	No	Overrides the Body property when connected. Accepts String or Binary.
Headers	Map	No	Map of string keys to string values merged on top of the static Headers property.

Outputs

Port	Type	Description
> (Trigger)	Boolean	Fires true when the attempt is answered — a response of any status, or a transport failure with the retries spent; resets to false after the trigger path runs.
Status	Integer	HTTP response status code (e.g. 200, 404). Nil until the first response arrives.
Headers	Map	Response headers as a string-to-string map. Nil until the first response.
Body	String	Response body as a UTF-8 string. Nil until the first response.

Properties

Name	Type	Default	Description
Method	Combo	GET	HTTP method: GET, POST, PUT, PATCH, or DELETE.
URL	TextLine	""	Request URL. Must use http:// or https://. Overridden by the URL input when connected.
Headers	Block (table)	empty	Static request headers as Header / Value rows. Merged with the Headers input (input wins on conflict).
Body	TextBox	""	Static request body. Overridden by the Body input when connected.
Request Timeout	Duration (seconds)	30 s	Per-request timeout. Requests that exceed this are treated as errors.
Max Response Bytes	Integer	0 (plan limit)	Per-request response size cap in bytes. 0 defers to the plan-level cap (see Egress Limits below).
Retry attempts	Integer	0	Re-issues after a transport failure, 0 to 5. GET only: a repeated request of any other method can deliver twice, so the Node refuses to compile with retries on another method.
Follow Redirects	Boolean	true	Follow HTTP redirects (up to 5).
On Error	Combo	Stop this branch	Per-op On Error verb (Stop this branch / Continue with the last value / Continue with the fallback). See the Error Handling guide.

On Error governs the answer

A transport failure with the retries spent is this Operation’s failure, and it arrives on the follow-on Path this Operation roots: the Path fires, the failure is reported there, and the Node’s On Error verb resolves it — Stop this branch stops the Path at this Node, while Continue with the last value and Continue with the fallback carry a value on to the dependents, flagged as a failed update. A non-2xx response is a response: the Path fires and Status carries the code. See Operations that answer later.

State on Reload

REST API Call does not persist state across restarts. In-flight requests at the time of a reload are abandoned; the trigger path for those requests will not fire.

---

How It Works

1. Gate check — If the Gate input is connected, a false or Nil value stops the execution path; the request is not issued.

2. Egress budget check — The per-slot egress budget is checked: rate limit (requests per minute) first, then concurrency cap. If either is exceeded, the request is not issued: the Node fails with an Egress: limit exceeded status and no follow-on Path fires that round.

3. Client check — A request leaves through the slot’s shared HTTP client. Where the slot carries none, the reservation taken above is returned and the Node fails with an Egress: this slot has no HTTP client, so the request cannot be issued status.

4. Request build — The URL, Method, Headers, Body, and timeout are resolved (input overrides win over property values).

5. Async dispatch — The request is issued asynchronously. The caller’s execution path ends here; the trigger path is not launched yet.

6. Completion — A response of any status fires the follow-on Path with Status, Headers and Body. On a transport failure the request is re-issued while Retry attempts remain; when they are spent the Path fires all the same, carrying the failure, and the Node’s On Error verb decides what the Path sees.

---

Egress Limits

Each slot has a shared egress budget consumed by all REST API Call and Webhook operations in that slot — a concurrency cap, a per-minute rate, and caps on request and response size. The budget is checked before the request is issued: a request that fails either the rate limit or the concurrency cap is never issued, and the Node fails with an Egress: limit exceeded status.

The keys, their defaults, and the values per plan are in the Extras configuration reference. On the Free tier maxConcurrent is 0, which disables egress operations entirely.

The Max Response Bytes property on the node sets a per-request cap; leaving it at 0 defers to the slot-wide cap. The per-request cap cannot exceed it.

---

Destination Safety

REST API Call sends a request to whatever the URL resolves to, and that URL can come from the URL input rather than the property — so the destination is not always one you fixed when you built the Task.

• The cloud instance-metadata endpoint is refused by default. A request whose host is 169.254.169.254, written in any numeric form, or one of its IPv6 forms fails with blocked: cloud metadata endpoint. The extras.egress.allowCloudMetadata key re-allows it for a deployment that genuinely needs it.
• Every redirect hop is checked, not just the URL you typed. The check sits at the connect seam, so a Location that points at a blocked destination is refused on that hop.
• Credentials do not follow a redirect off-origin. A redirect that crosses to a different origin drops credential-bearing headers before re-issuing, so an Authorization header set in the Headers property or input cannot be replayed to a host you did not address.
• A header cannot split the request or add another header. The method and every header name must be an HTTP token: letters, digits and !#$%&'*+-.^_`|~, with no space or :. CR, LF and NUL are rejected in every header value. A request that breaks either rule fails (invalid method: not a token, invalid header: name is not a token, or invalid header: CR/LF not allowed) rather than being silently stripped, so a header fed from a Task input cannot smuggle a second header or request onto the wire.
• On a hosted slot the deployment blocks private destinations outright, at the kernel, which is what makes it hold for a hostname that resolves to a private address. A station deliberately does not: reaching devices on the local network is why you run one.

A URL from an untrusted source is a destination you did not choose

When the URL input is fed from a webhook payload, a database row, or anything else that crosses a trust boundary, the request goes wherever that value says. Validate it against an allowed host list before wiring it in.

See Destination safety in the configuration reference for the full picture.

---

TLS Verification

HTTPS connections, every redirect hop included, always verify the server against the system CA bundle. The operation has no setting that turns verification off or supplies another CA.

---

Concurrency

Each in-flight request owns its own HTTP client. Overlapping requests (e.g. from a high-frequency trigger) do not clobber each other: each fires its own trigger path with its own response when it completes, in any order. The shared egress budget (concurrency cap above) limits how many can be in flight at once.

---

After a failure

Retry attempts are spent first: each transport failure re-issues the request while attempts remain. Once the budget is exhausted the completion fires the follow-on Path all the same, carrying the failure instead of a response, and the Node’s On Error verb decides what that Path sees:

Verb	What the follow-on Path sees
Stop this branch (default)	Fires, and stops at this Node: nothing downstream runs. Status, Headers and Body keep their values, and the attempt reads as failed.
Continue with the last value	Fires. Status, Headers and Body keep their values, not stamped as new; the attempt reads as failed.
Continue with the fallback	Fires. Each output carries its per-output Fallback, stamped as this run’s value; the attempt reads as failed. The Editor refuses a Task where a Fallback is unset.

A non-2xx response is not a failure: the Path fires and the Status output carries the code, whichever verb the Node carries.

---

Use Cases

• Webhook fan-out — a Scheduler fires once a minute, SQLiteStorage reads pending records, REST API Call posts each to an upstream API.
• Polling — a Scheduler calls a status endpoint; a JavaScript node parses the JSON body and routes on the result.
• API write-back — after AI classifies an event, REST API Call posts the classification to an external ticketing system.
• Health check — REST API Call hits a /health endpoint; a Condition node routes on the Status output (200 → OK, anything else → alert).
• Sending email — a threshold breach calls your email provider’s HTTP API (SendGrid, Postmark, SES, Mailgun) with the API key in a Header and the message in the Body. This is how a Task sends mail: Nonbl has no email operation, because mail sent from the platform’s own addresses would carry the platform’s sending reputation, and one misconfigured Task would put every other tenant’s delivery at risk. Calling your provider keeps the reputation on your own account, where you control it.

---

Notes

• The URL must use http:// or https://. Other schemes (ftp://, etc.) are rejected at task-load time.
• The rest of the URL is checked when the request is made. The host is a name of letters, digits, -, . and _, a dotted-quad IPv4 address, or an IPv6 address in brackets (http://[2001:db8::1]:8080/). A port is 1–65535. Credentials in the URL (user:password@) are refused, and a #fragment is not sent. A refused URL fails with invalid URL, which does not repeat the URL: its path or query can hold a secret.
• The static Body property is stored in plaintext in the task file. Use the Body input (fed from a SQLiteStorage or JavaScript node) for secrets or dynamic content.
• Request headers are case-insensitive per HTTP spec; response header keys in the Headers output are normalized to lowercase.
• The operation is not suitable for very high-frequency triggers (per-message MQTT streams). Batch or decimate with a Scheduler, Counter, or Hysteresis node first.