REST Request Step

Description

The REST Request step calls a REST API as one step in a workflow. It’s a single, Postman-style step for the whole “build → send → inspect” loop: pick an endpoint (typed in by hand or imported from a Postman collection, an OpenAPI/Swagger spec, or a HAR capture), set headers, query parameters, and a body, fire a test request to see the live response, then save the step.

You choose where the response goes. By default it’s parsed into a table. Alternatively, the step can capture the response into workflow variables so a later step can branch on the status code or read a value out of the body.

If you close or reload the browser before saving, the editor keeps a local draft in that browser. Reopen the same step and choose Restore when prompted to recover the unsaved request settings.

Note

The REST Request step replaces the older REST-flavored steps with one unified step. Use it for new work; existing REST steps keep running.

Before You Start

You’ll usually want a connection of the REST kind, which holds the base URL and authentication for the service. The step can also call a fully-qualified URL directly without a connection. See REST connections.

Add a REST Request Step

1. Open the workflow and add a step where you want it.
2. Choose REST Request (unified) as the step type (under the REST steps). The editor opens with a Request tab, a Response tab and a Table Data Selection tab.

Build the Request

In the Request tab:

Endpoint Source

Pick how you’ll supply the endpoint, then PlaidCloud fills in the request for you:

• Manual — type the method and URL yourself.
• From the connection’s API definition — use the OpenAPI/Swagger definition stored on the connection you picked, so you don’t restate it on every step. See Reuse a Connection’s API Definition below.
• Postman collection (file) / Postman collection (URL) — import from a Postman collection.
• OpenAPI / Swagger (URL) / OpenAPI / Swagger (file) — import from an API spec.
• HAR archive (file) — import a request captured from your browser’s network log.

For an imported source, choose Load Catalog to list the available endpoints, then pick one under Endpoint. The step fills in its method, URL, headers, query parameters, and body, using each parameter’s example or default value; an optional parameter with neither starts switched off. If the request already holds something you entered, the step asks before replacing it. Press Ctrl+Z (Cmd+Z on a Mac) when you’re not typing in a field, or choose Undo replace, to put the previous request back.

A large catalog is easy to narrow: type in Filter by method, path or name… to list only the matching endpoints. The catalog shows how many endpoints it holds (12 of 340 while filtered) and when it was loaded, and the step notes when a very large definition was cut at its preview limit.

Paste a Collection or Spec Instead of Picking a File

The three file-based sources — Postman collection, OpenAPI/Swagger, and HAR archive — each offer a Paste… button beside the file picker. Use it when you have the content to hand but haven’t saved it to Document: paste the JSON and choose Use This. The catalog loads straight away, so there’s no need to click Load Catalog afterwards.

Pasted content is used in place of the file picker, and lasts as long as the step stays open — it isn’t saved with the step, so paste it again if you reopen the step and want to reload the catalog from it. If you pick a file for that same source, the file wins and the pasted content is discarded — the step tells you when that happens.

You can also drop a .json file onto the source picker. The step checks the content against the source you chose and tells you what’s wrong, such as a Postman collection pasted where an OpenAPI spec is expected or a file that isn’t JSON, and each source has a How do I get a …? link that explains how to export a Postman collection, an OpenAPI spec, or a HAR file.

Note

Paste and drop accept JSON. For a YAML spec, save the file to Document and pick it instead.

Reuse a Connection’s API Definition

Connectors built for a specific service already know their endpoints. Generic REST and MuleSoft connections don’t — they can point at any API — so they let you attach the API’s definition to the connection itself.

Set it once on the connection (see Generic REST Connection), then in any step that uses that connection:

1. Pick the connection under Connection.
2. Set Endpoint Source to From the connection’s API definition.
3. Choose Load Catalog and pick your endpoint.

Every step sharing that connection offers the same endpoint list, and updating the definition on the connection updates them all.

Connection Summary and Environment

Under the Connection picker, a summary line shows what the step will use: the authentication type, the host, and how many default headers the connection sends with every request. Choose the refresh button beside the picker after you change the connection to reload its authentication, host, and default headers without reopening the step. When the connection defines environments, the Environment picker chooses which one the step runs against.

Note

A definition URL must be reachable from the internet. If your API’s specification is only published inside your own network, upload the file to Document and select it on the connection as a file instead.

Connection, Method, and Endpoint

• Connection — the REST connection to authenticate with. Leave it unset to call a fully-qualified URL directly. Use the edit shortcut beside the picker to view or edit the selected connection without leaving the request editor.
• Method — GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS.
• Endpoint — the path (when a connection is set) or a full URL.

Headers, Query Parameters, and Body

• Headers and Query Parameters are editable tables of name/value rows, each with an On toggle and a description. Add rows with Add and remove them with Remove.
• Body holds the request payload (JSON, form, or raw) in a code editor.

Format JSON indents the body, and Validate JSON checks it and reports the line and column of any error. Both read each {{…}} variable as a value, so your variables stay exactly as written. Variables reference… lists every variable you can use in the request, and Insert {{…}} puts a variable at the cursor.

While you edit, the step flags problems under the request:

• A header or query parameter name that appears twice, where one value would be lost.
• A header name that looks mistyped, with a Did you mean… suggestion, such as Authorisation for Authorization.
• A secret, such as an Authorization or X-API-Key value, typed in plain text. Keep it in a project variable and write {{project_var.NAME}} so the secret isn’t stored in the step.
• A JSON body with no Content-Type: application/json header, which some servers refuse with HTTP 415.
• A URL with a mistyped scheme, a double slash in the path, a trailing slash, or stray spaces.

Variable Substitution

Anywhere in the endpoint, headers, query values, or body you can inject a variable at run time by wrapping its name in double braces: {{name}}. You can also write {{var.name}} for a workflow-run variable or {{project_var.name}} for a project variable — the prefix is optional and both resolve the same name.

The editor highlights detected {{...}} tokens in the endpoint, header and query tables, and body editor so substitutions are easy to spot before you test or save.

Only double braces are substituted, so a single { or } in a JSON body is left exactly as written — you can freely mix variables into JSON, for example {"id": "{{var.order_id}}", "qty": 1}. An unknown variable name fails the step so a typo surfaces immediately.

When the workflow is started by a sensor or webhook, four trigger variables are also available: {{trigger_sensor_id}}, {{trigger_sensor_type}}, {{trigger_fired_at}}, and {{trigger_payload_json}} (the inbound payload as a JSON string — parse it in a later step to reach nested fields). On a manual or scheduled run these resolve to an empty string.

Test the Request

• Send Test Request fires the request with your current settings and shows the live response inline, so you can confirm the call works before saving. Press Ctrl+Enter (Cmd+Enter on a Mac) to send from anywhere in the form. A status line shows the HTTP status and response time, and a timer counts up while the request is in flight. (This sends a single request; pagination runs only when the step executes.)
• Test Paging follows the configured pagination and reports how many records come back across pages (up to a preview cap), so you can confirm the paging mode and its params/paths chain correctly before a full run. Only enough pages fire to reach the cap.
• Copy as curl copies an equivalent curl command to the clipboard for sharing or debugging (with secrets masked).
• Import from curl does the reverse: paste a curl command — for example, a browser’s “Copy as cURL” — and its method, URL, headers, and body replace the current request. Basic-auth (-u) becomes an Authorization header; unsupported options are reported rather than silently dropped. Use Undo replace to restore the previous values.

The response opens in a viewer with Pretty and Compact views. The last five test results are kept while the step is open, and you can pick one to view it again or re-run it. When the response holds a list of records, Suggest sets Items path to the first list it finds.

The Request Preview group shows the request exactly as a run would send it, with variables resolved and secrets masked, without sending anything. Choose Refresh Preview after you edit.

If you change the outbound request fields and save before a successful Send Test Request, PlaidCloud asks Save without a successful test? and you choose Save anyway or go back. In fan-out mode, use Test Row 1 to test the first driver row before saving.

Route the Response

In the Response tab, set the Response Destination:

Table (default)

The response is parsed into the Target Table, which is required in this mode. Pick an existing table, or create one from the picker; views aren’t offered. The Pagination & Parsing group controls how:

• Row format — Object (the default) when each record is a JSON object, or Array when each record is a list of values. Array isn’t available with One request per table row. Items path says where the records live inside the response.

• Pagination mode — No Paging (the default), Offset Paging, Page Number Paging, Next Page URL Paging, Cursor Paging, or Link Header Paging (RFC 5988). Mode params and Mode paths say which parameters and response fields drive the paging, and they’re available only when a paging mode is chosen. Choosing a mode fills both with its defaults, which you can edit.

  Mode	Mode Params Default	Mode Paths Default	How It Pages
  Offset	{"offset": "offset", "limit": "limit"}	{"has_more": ["has_more"]}	Sends the offset and limit query parameters, and reads on while the response’s has_more is true.
  Page Number	{"offset": "page"}	{"has_more": ["has_more"]}	Sends the page number in the page parameter, and sends no limit.
  Next Page URL	{}	{"next": ["next"]}	Requests the URL found at the next path of each response. A relative URL is read against the page it came from.
  Cursor	{"cursor": "after"}	{"has_more": ["has_more"], "cursor": ["next_cursor"]}	Sends the cursor from the previous response in the after parameter. Add "send_as": "header" or "send_as": "body_field" to Mode params to send it as a request header or a body field instead. To read the cursor from a response header, such as the x-ms-continuation header Azure Cosmos DB sends, put "token_header": "x-ms-continuation" in Mode paths in place of has_more and cursor; the last page is the one without the header.
  Link Header	{"rel": "next"}	{}	Follows the Link response header’s relation named by rel.

  Offset and Page Number accept more keys in Mode params: start is the first offset or page number (default 0), stop_on_empty stops at the first page with no records at the items path, so the response needs no has_more field, and send_limit says whether the limit parameter is sent (default true for Offset, false for Page Number).

• Dump raw JSON instead of parsing rows — store the raw payload rather than parsing it into columns.

• Retries (0 to 100) and Timeout (s) (1 to 600) — how the request behaves under failure and how long it may run. A run waits up to the timeout you set; Send Test Request, Test Row 1, and Test Paging wait at most 300 s. Retries cover connection failures, server errors (5xx), and rate limiting (HTTP 429) for idempotent methods (GET, HEAD, OPTIONS, DELETE). A POST, PUT, or PATCH is retried only after a rate-limit (HTTP 429) response, which tells you the server did nothing with it, and never after a server error, so a non-idempotent request body is never sent twice after the server may have acted on it; when the API returns a Retry-After header, the step waits the interval it asks for (capped at 2 minutes) before retrying.

The Table Data Selection tab maps the response’s fields to the target table’s columns. Inspect Source → Populate fills the mapping from a live response: it sends the step’s request through its connection, as a run would. It needs a connection, and asks first when the method is anything other than GET, HEAD, or OPTIONS. Summarize and Distinct aren’t offered here, because the step writes the parsed response straight to the target table.

Workflow variables

Set Destination to Workflow variables and give a Variable prefix (a plain name such as my_call). The step fires one request and writes four workflow variables:

Variable	Contents
{prefix}_status	HTTP status code (for example, 200).
{prefix}_body	Response body as a string (JSON responses are stored as JSON text).
{prefix}_headers	Response headers as JSON text.
{prefix}_elapsed_ms	How long the request took, in milliseconds.

Reference them downstream like any workflow variable — for example {my_call_status}. This is the building block for “fire one request, then branch on the result” patterns.

Caution

The prefix must start with a letter or underscore and contain only letters, digits, and underscores. It can’t be one of the reserved names cloud, project, model, or date. In variable mode the step captures a single response — pagination and row parsing don’t apply.

Send One Request Per Table Row

By default the step sends one request. To call an API once per row of a table — for example, look up every customer id in a table, or POST each row as a record — set Send (in the Request tab) to One request per table row. This reveals the driver-table fields:

• Driver Table — pick the table whose rows drive the requests. Choose it from the workflow’s tables with the picker, or type a table name. Each row’s columns are available as {{row.column}} tokens.
• Driver Filter (optional) — a SQL WHERE clause that limits which rows are used.
• Key Columns (optional) — comma-separated driver columns to carry through onto every output row, so the results join back to the driver.
• Row Limit and Concurrency — the maximum number of rows to process and how many requests run at once.
• Max req/sec (optional) — cap how fast requests start across all workers so a burst doesn’t trip the API’s rate limit (0 = no limit). The value can be a fraction: 0.5 starts one request every two seconds. A value over 1000 runs as 1000 with a warning. This is independent of Concurrency: concurrency bounds how many run at once, while Max req/sec paces how often a new one starts.
• Add Idempotency-Key header (optional) — for a single (No Paging) POST, PUT, or PATCH request per row, sends a stable Idempotency-Key header derived from each row so that re-running the step doesn’t double-create records on an idempotency-aware API (the same row always sends the same key, so the API dedupes the repeat). It’s ignored, with a warning, for GET/HEAD/DELETE or when a paging mode is on. A request that already sets its own Idempotency-Key keeps it.
• Response — how each response becomes rows. Parsed records (default) writes each response record as a row. Text (one row per request) writes one row per request with DownloadData and DownloadHeaders columns; a failed request is dropped. Raw text, errors as rows also writes one row per request, but keeps the body exactly as the server sent it, adds a DownloadStatus column, and keeps an HTTP or transport error as a row with its error body and status. Credentials are masked in the body, headers, and error text of every raw row, and a redirect to a different origin isn’t followed on a request that carries credentials. Paging doesn’t apply to the text modes. In Text (one row per request), Keep error response (keep_error_response) writes the body of an HTTP 400 or higher response to the row as it does for a success, instead of failing the row, and Response meta (response_meta) adds DownloadStatus, DownloadReason and DownloadUrl columns holding the response’s status, reason and final URL. Both are off by default and are set with an AI assistant or the REST API.
• Continue on error — when on, a row that fails is recorded and the step ends with a warning instead of aborting on the first failure. The run log names the first few failed rows (by their key columns) and the error each hit, so you can tell which rows failed and why.

Use {{row.column}} tokens anywhere in the endpoint, query, headers, or body to substitute that row’s values — for example GET /customers/{{row.customer_id}}. A value in a query parameter is URL-encoded once, so the server receives A 1 and a/b as typed. Earlier versions encoded it twice, and the server received A%201 and a%2Fb. If a POST, PUT, or PATCH step has Add Idempotency-Key header on and a row value that needs encoding in its query, its key changes once after the upgrade because the request changed. A re-run that straddles the upgrade can send one repeat request for each such row. Values made only of letters, digits, and -._~ are unchanged. Each row’s response records are parsed into the target table (with any key columns prepended); with Dump raw JSON on, you get one row per request instead.

The Insert {{row.column}} menu lists the selected driver table’s columns, so you can drop a {{row.customer_id}}-style token into the endpoint or body — whichever field you edited last — instead of typing column names by hand. As you edit, the form also lists the {{row.column}} tokens you’ve used and highlights in red any that aren’t a column of the driver table, so typos are caught before you run the step.

Test Row 1 reads the first driver row (honoring the driver filter), substitutes its values into the endpoint, query, headers, and body, and fires that one request — so you can confirm the fan-out is wired correctly before running it over every row. The response is shown inline like Send Test Request, along with the driver-row values that were used. Preview Row 1 likewise resolves the first driver row’s {{row.column}} values and shows the resolved request without firing it.

Note

One request per table row writes to a table — it can’t capture to workflow variables. The response destination stays Table.

Run the Step

The REST Request step runs like any other — as part of a full run or on its own (see Running one step in a workflow). In table mode it writes the parsed (or raw) response to the target table; in variable mode it sets the four variables for later steps to read.

Next Steps

• REST Request step reference — concise field list
• Manage workflow variables — read and set variables across steps
• REST connections — set up authenticated API connections