API workflow nodes

Docs for

API workflow nodes

You are viewing documentation for Buttons 1.8.See the docs for Buttons 1.6

API workflow nodes

Use these nodes to exchange data with external systems. Listener and server nodes open network ports, so configure authentication and exposure deliberately.

Choose a node#

OSC Listener: listen for open sound control (osc) messages on a udp port
REST Server: expose selected workflow values and triggers as http endpoints
HTTP Request: send one http request when another node triggers it
HTTP Query: fetch and refresh data from an http endpoint
TCP Server: accept tcp client connections and exchange messages (experimental)
TCP Client: connect to a tcp server and exchange messages (experimental)
UDP Receiver: receive udp datagrams on a local port (experimental)
UDP Sender: send udp datagrams to another host (experimental)
WebSocket Client: connect to a websocket server and exchange messages (experimental)
WebSocket Server: accept websocket clients and exchange messages (experimental)

OSC Listener#

Listen for Open Sound Control (OSC) messages on a UDP port.

What you see in the editor#

The card header reads OSC Server, even though this node is listed and referred to elsewhere as OSC Listener.
Set Port: accepted values are 1024–65535; a lower value shows a Too small: expected number to be >=1024 error and the node won't start. Then use Add Path to add each OSC path the workflow should accept. Each path's editor popover reminds you of the supported syntax: :param for a single named segment, * to match one segment, and ** to match many.
For a path such as /scene/:name, the node creates an event for that path and makes each :name-style segment available as its own output. Only :param segments produce an output: * and ** wildcards match but don't expose a value.

Connections#

Kind	Label	What it provides
Output events	One per configured path	Fires when an incoming OSC address matches that path.
Outputs	One per `:param` in the path	The latest value received for that named segment.
Output	Arg 1	The first OSC argument from the matched message, regardless of how many arguments it carried.

Example#

Add /scene/:name, send /scene/main from a test client, and use the resulting event and name value downstream.

REST Server#

Expose selected workflow values and triggers as HTTP endpoints.

What you see in the editor#

Set Port: accepted values are 1024–65535. Rate Limit is a preset dropdown (10 reqs / min, 100 reqs / min, 1000 reqs / min, or Off), not a custom number. Add one or more Bearer Tokens to require that token on every endpoint (GET and POST alike; there's no per-endpoint auth control). Configure both before exposing the server to another system.
Use Add Endpoint to enter a Path and choose GET or POST. A GET endpoint returns its connected value. A POST endpoint updates its output and fires an event.

Connections#

Kind	Label	What it provides
Input	One per GET endpoint	The value returned by that endpoint.
Output	One per POST endpoint	The latest request body.
Output event	One per POST endpoint	Fires when a request reaches that endpoint.

Example#

Create an authenticated GET /status endpoint for a non-sensitive workflow value and test it from the intended network.

See Expose a small authenticated REST endpoint from a workflow for a full walkthrough, including bearer-token rotation and restart behavior.

HTTP Request#

Send one HTTP request when another node triggers it.

What you see in the editor#

Enter URL. Choose Method from GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS, and Content Type from JSON, JSON (UTF-8), Form URL Encoded, Octet Stream, or Text: both are dropdowns, not free text. Set Timeout (ms) from 0 to 300000 (default 30000).
Under Authentication, choose None, Bearer Token, or Basic Auth. Select stored Secrets for tokens and passwords rather than typing credentials into the workflow.
Use this node for one-shot requests. Use HTTP Query for automatic polling.

Connections#

Kind	Label	What it provides
Input event	Trigger	Sends a request using the values configured on the card.
Input event	Request Object	Sends a request with event-provided overrides.
Inputs	URL, Method, Headers, Body	Override or supply request values.
Output events	onSuccess, onError	Continue according to the result.
Outputs	Body, Full Response, Error, Status Code	Inspect the latest response.

Example#

Connect a Button to Trigger, make a harmless read request, and display Status Code while testing.

See Call an HTTP endpoint from a workflow for a full walkthrough, including timeout and error-handling behavior.

HTTP Query#

Fetch and refresh data from an HTTP endpoint.

What you see in the editor#

Enter URL. Choose Method from GET, POST, PUT, PATCH, DELETE, or HEAD (no OPTIONS here, unlike HTTP Request), Content Type from the same five options as HTTP Request, Timeout (ms) from 1000–300000 (default 30000), and Authentication.
Choose a Retry Strategy: Exponential Backoff (capped by Max Backoff (ms), 1000–600000, default 60000) or Fixed Interval (Retry Interval (ms), 500–60000, default 5000). Toggle Infinite Retries, or set Max Retries (0–100, default 3). Only failed requests with a 5xx status or a timeout are retried; a 4xx response is not.
Refetch Interval is a switch that's on by default: with it on the node polls automatically every Interval (ms) (1000–3,600,000, default 10000) even if you never touch this section. Turn it off for a query that should only run once or on demand.
Set Cache Mode: Never Cache, Cache Until Retry Fails (default), or Cache Until Success, and optionally enable Expire Cache After Timeout with an Expire After (ms) value (1000–86,400,000).
The status panel shows the current state, status code, error, and a preview of the last response. Use Refetch to fetch now. Retry becomes available after an error.

Connections#

Kind	Label	What it provides
Input	Enabled	Stops all fetching when false.
Input event	Invalidate	Starts an immediate fetch.
Inputs	URL, Headers, Params, Body	Supply request values.
Output events	onSuccess, onError, onSettled	Respond when a request completes.
Outputs	Status, Data, Error, isLoading, isError, isSuccess, Status Code	Use the latest query state and response.

Example#

Poll a read-only status endpoint and connect isSuccess and Data to the workflow’s display logic.

TCP Server#

Accept TCP client connections and exchange messages.

Experimental

This node is hidden behind an internal, developer-only setting: it is not available through Settings → Features in this release. Its behavior and support status can change without notice.

What you see in the editor#

Set Port (1024–65535). If messages use a delimiter, configure Delimiter, Buffer until delimiter, and Max Buffer Size (bytes) (1024–10,485,760, default 65536).

Connections#

Kind	Label	What it provides
Input event	Send (Event)	Sends an event payload to connected clients.
Input	Send (State)	Sends value updates.
Output event	Message Event	Fires when a complete message arrives.
Outputs	Connected, Connections, Last Message, Last Object, Last Timestamp, Last From IP, Last From Port	Describe the server and latest message.

Example#

Connect a test client, send one delimited message, and inspect the latest-message outputs before connecting actions.

TCP Client#

Connect to a TCP server and exchange messages.

Experimental

This node is hidden behind an internal, developer-only setting: it is not available through Settings → Features in this release. Its behavior and support status can change without notice.

What you see in the editor#

Set Target Host, Target Port (1–65535), and Reconnect Interval (ms) (1000 minimum, default 5000).
Use the idle-disconnect and state re-emission controls only when the remote server’s behavior requires them. Configure delimiter buffering to match the protocol.

Connections#

Kind	Label	What it provides
Input event	Send (Event)	Sends an event payload.
Input	Send (State)	Sends value updates.
Output event	Message Event	Fires for each complete received message.
Outputs	Connected, Last Message, Last Object	Show connection and message state.

Example#

Connect to a non-production TCP endpoint, confirm Connected, then send and receive a known test message.

UDP Receiver#

Receive UDP datagrams on a local port.

Experimental

This node is hidden behind an internal, developer-only setting: it is not available through Settings → Features in this release. Its behavior and support status can change without notice.

What you see in the editor#

Set Port (1024–65535). Configure delimiter buffering only when one datagram can contain partial or multiple application messages.

Connections#

Kind	Label	What it provides
Output event	Message Event	Fires for each complete received message.
Outputs	Last Message, Last Object, Last Address, Last Port	Show the latest payload and sender.

Example#

Send a known datagram from a test host and use Last Address and Last Message to confirm its source and content.

UDP Sender#

Send UDP datagrams to another host.

Experimental

This node is hidden behind an internal, developer-only setting: it is not available through Settings → Features in this release. Its behavior and support status can change without notice.

What you see in the editor#

Set Destination Host and Destination Port (1–65535). Leave Local Port (0 = auto) at 0 unless the receiving system requires a fixed source port.

Connections#

Kind	Label	What it provides
Input event	Send (Event)	Sends an event payload.
Input	Send (State)	Sends value updates.
Output event	Sent Event	Fires after a send.
Outputs	Last Sent, Sent To Address, Sent To Port	Show the latest send.

Example#

Send a harmless test value to a receiver on a non-production network and confirm the destination outputs.

WebSocket Client#

Connect to a WebSocket server and exchange messages.

Experimental

This node is hidden behind an internal, developer-only setting: it is not available through Settings → Features in this release. Its behavior and support status can change without notice.

What you see in the editor#

Set URL and Reconnect Interval (ms) (1000 minimum, default 5000).
Use idle disconnect and state re-emission only when they match the remote server’s expectations.

Connections#

Kind	Label	What it provides
Input event	Send (Event)	Sends an event payload.
Input	Send (State)	Sends value updates.
Output event	Message Event	Fires for each received message.
Outputs	Connected, Last Message, Last Object	Show connection and message state.

Example#

Connect to a test WebSocket server, confirm Connected, and exchange a known message.

WebSocket Server#

Accept WebSocket clients and exchange messages.

Experimental

This node is hidden behind an internal, developer-only setting: it is not available through Settings → Features in this release. Its behavior and support status can change without notice.

What you see in the editor#

Set Port (1024–65535). Enable Emit on connect only when a new client connection should produce an event.

Connections#

Kind	Label	What it provides
Input event	Send (Event)	Sends an event payload to clients.
Input	Send (State)	Sends value updates.
Output events	Message Event and connection event	Report messages and, when enabled, client connections.
Outputs	Connected, Connections, Last Message, Last Object	Show server and message state.

Example#

Connect a test client, confirm the connection count, then exchange a known message before connecting operational actions.

Was this helpful?

0 of 0 users found this page helpful

← Position workflow nodes

Utility workflow nodes →