REST API node

The REST API node calls an external HTTPS API when a run executes it and turns the JSON response into rows on its output port. You configure it in one of two modes: Manual, where you write the request yourself, or OpenAPI, where you pick an operation from the API’s published specification and Flow builds the request form and the output columns from it. Credentials are workspace secrets in both modes.

Modes

Mode	You configure	Requests per execution	Ports
Manual	Endpoint, method, headers, query parameters, body, and authentication	Exactly one	Output
OpenAPI	Spec URL, base URL, authentication, an operation, and a binding for each of its fields	One, one per input row, or one per batch of values	Input and output

A new node starts in Manual mode. Switching to OpenAPI adds the input port; switching back to Manual removes it.

Manual mode

You enter the endpoint, the method (GET, POST, PUT, PATCH, or DELETE), headers, query parameters, and a JSON body. Each time a run executes the node, it sends that one request with the values you configured, whatever the method. POST, PUT, and PATCH send the body as application/json.

The response must be JSON. Flow reads its rows from the shape of the response:

An array: one row per item.
An object with a data array: one row per item of data.
Any other object: one row.
A scalar item: a row with a single value column.
HTTP 204 or an empty body: zero rows.

OpenAPI mode

Spec URL and Fetch spec

Enter the URL of the API’s specification and the authentication the API expects, then choose Fetch spec. Fontana downloads the specification with that authentication when the spec URL and the base URL are on the same origin (or no base URL is set yet), and without it when they differ, so your API credentials never go to a separate documentation host. Flow stores a copy with the workflow in the workspace’s .fontana system folder, in the workspace history. After the first download the button reads Refresh spec; choose it whenever the API publishes a new version.

Supported versions: OpenAPI 3.0, OpenAPI 3.1, and Swagger 2.0, in JSON or YAML. Flow converts Swagger 2.0 to OpenAPI 3 when it downloads the specification.
References: every $ref must point inside the same document (#/...). A specification that references another file or URL is rejected.
Size: up to 10 MiB.

The stored copy is for editing only. A run reads everything it needs from the node’s configuration, so a run never depends on the copy. If you rename the workflow, the editor asks you to refresh the specification before you edit the operation again. Removing the node removes its copy.

The Base URL is where the requests go. Flow fills it in from the first server the specification lists, or from the origin of the spec URL when the specification lists none. You can change it, and Refresh spec never overwrites it.

Operation

Pick the operation you want to call from the list of the specification’s operations, grouped by tag. You can search the list. The operation sets the method and the path; the canvas node shows both.

Bindings

For the operation you pick, Flow lists a binding row for each path, query, and header parameter, and for each top-level property of the JSON request body. When the body is an array, one row stands for the whole body. Each row takes one kind of binding:

Binding	What the request sends	Available for
Static	The value you enter. Objects and arrays are edited as structured values.	Every field
Column	The value of a column of the current input row. The node sends one request per input row.	Every field
Batch column	The values of a whole input column as one array, 100 values per request.	Array fields
Secret	The value of a workspace secret you pick.	Header and query parameters

Per row or batched: one operation uses Column bindings or a Batch column binding, not both.
Request columns: with Column bindings, each output row starts with the values those bindings sent, as columns named request_<name>, so you can match every response row to the input row that produced it.
Column list: the column picker lists the columns of the node connected to the input port. If Flow cannot tell the columns yet, it asks you to run the upstream node first.
Query arrays: array values are written in the style the specification declares for the parameter, by default as a repeated key (?isin=A&isin=B).
Path values: each path parameter is URL-encoded. An empty value, ., or .. fails the row.
Headers Fontana sets: Authorization, Proxy-Authorization, Cookie, Accept, and Content-Type come from the authentication and the operation, so the binding list leaves them out.
Nested bodies: a property that holds objects or arrays of objects takes a static value; binding columns inside it is not available.

Typed output and record path

The node declares its output columns from the operation’s first successful (2xx) JSON response in the specification. Downstream nodes see those columns before the first run, the same way they see the output of a Schema node.

The Rows picker sets the record path: where the rows sit in the response. Flow proposes the root when the response is an array, or the only array property of the response object; you can pick another array in the response. When the path holds a single object, that object is one row.

Every response is checked against the declared output:

Type mismatch: a field whose JSON type differs from the specification fails the node, and the error names the record and the field.
Undeclared fields: fields the specification does not declare are dropped from the output rows.
Formats and patterns: format, enum, and pattern are documentation only; the check compares JSON types.
HTTP 204 or an empty body: zero rows.

Authentication

One authentication setting serves both the specification download and the API requests. Passwords, tokens, API keys, and client secrets are always workspace secrets. Usernames and client IDs take a plain value or a secret. Use Choose secret or Create secret inside the field; a chosen secret shows as a padlock badge with its name.

Mode	Fields	What Fontana sends
None		No credentials
Bearer token	Token	`Authorization: Bearer <token>`
Basic auth	Username, password	`Authorization: Basic` with both
API key	Key, and a header name or a query parameter name	The key in that header or query parameter
Form login	Login page URL, username, password	A signed-in session cookie
OAuth2 token	Token URL, grant type (client credentials or password), client ID, client secret, client authentication (Basic header or Request body), scope	`Authorization: Bearer` with the access token the token URL returns

Form login signs in the way a person does in a browser, for APIs that use a login page and a session cookie:

Fontana opens the login URL and finds the login form the way a browser’s password manager does: the first form with exactly one password input that is not a new-password field, so sign-up forms are skipped. The username input is the one marked autocomplete="username", or else the last text, email, phone, number, or URL input before the password input. You do not name the inputs.
It submits the form with its hidden fields, your username and password, and the form’s default submit button. The form must post to the login page’s own origin.
Sign-in succeeds when the response redirects away from the login page and sets a session cookie. Otherwise the node fails with form login rejected and the HTTP status.

The session cookies go only to the login page’s origin, so the login URL and the API share one origin. Some sites answer a wrong password with a redirect as well. Then the first API request is sent back to the login page, and the node fails with form login rejected and the HTTP status.

OAuth2 token

You enter the token URL yourself. Fontana requests an access token with the grant you chose and sends it as a bearer token. Without a client secret, Fontana sends the client ID as a public client. A failed token request reports the HTTP status only.

Test request

Test request sends the configured request once from the editor and shows the HTTP status and the first 20 rows. In OpenAPI mode, Column and Batch column bindings use sample values. Test request uses the workspace’s secrets, so it is available to workspace editors and admins, and Fontana limits how often you can send one.

Limits

The node enforces the same limits on every run and test:

Limit	Value
Destination	HTTPS on port 443, to a public address. Fontana checks the address of every URL it calls, including each redirect.
Redirects	At most 5, on the same origin
Response size	10 MiB per response, decoded
Total response size	50 MiB per node execution
Request timeout	30 seconds per request
Execution timeout	5 minutes per node execution
Requests	1,000 per node execution; each batch counts as one
Concurrent requests	4
Batched request body	1 MiB

When any request fails, the node fails with the input row or batch and the HTTP status, and it publishes no partial output.

When the node runs

The node runs again when its configuration or its input changes, or when you choose Refetch data in the canvas node’s options menu (it reads Fetch data before the node has output) or in the editor. Refetching works for every method, so use it when you want to send a POST, PUT, PATCH, or DELETE again without changing the node.

A node with no endpoint (Manual) or no operation picked (OpenAPI) stays idle and the run continues. With Column or Batch column bindings and no input rows, the node sends no request and outputs zero rows.

Workspace secrets - credentials for authentication and secret bindings
Ingress - every way data enters a workflow
Egress - every way data leaves a workflow
Workflow orchestration - when nodes execute in a run