REST API

🔗

REST API

Call external APIs with full request and response control

The REST API node makes HTTP requests to any REST endpoint. It supports all standard HTTP methods, custom headers, request bodies, authentication schemes, and SSL configuration. This is the most flexible integration node, suitable for connecting to any system that exposes an HTTP API.

Common uses include:

• Fetching data from third-party services.
• Submitting form data or JSON payloads to external systems.
• Updating records in remote applications.
• Deleting resources through API calls.
• Chaining multiple API calls in a single workflow.

Before You Use This Node

What you may need	Where to set it up	Why it matters
API request collection	API	Save reusable API requests in one place, similar to Postman.
Base URLs, tokens, or common headers	Global Variables	Avoid typing sensitive or repeated values in every API step.
Certificates for secure calls	Certificates	Reuse trusted certificates when an API requires them.

Actions

Action	Description
restApi:get	Send an HTTP GET request
restApi:post	Send an HTTP POST request with a body
restApi:put	Send an HTTP PUT request with a body
restApi:patch	Send an HTTP PATCH request with a body
restApi:delete	Send an HTTP DELETE request

---

Common Parameters

All REST API actions share the following parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	--	Full URL including protocol (e.g., https://api.example.com/v2/users)
headers	object	No	--	Key-value pairs of HTTP headers
queryParams	object	No	--	Key-value pairs appended as URL query parameters
auth	object	No	--	Authentication configuration (see Authentication Options)
timeout	integer	No	30000	Request timeout in milliseconds
sslVerification	boolean	No	true	Whether to verify SSL certificates
followRedirects	boolean	No	true	Follow HTTP redirects automatically
responseType	string	No	json	Expected response format: json, text, or binary
cookies	object	No	--	Key-value cookie pairs to include in the request

Body Parameters

The following parameters are available for actions that send a request body: restApi:post, restApi:put, and restApi:patch.

Parameter	Type	Required	Default	Description
body	object or string	Yes	--	The request body content
contentType	string	No	RAW	Body format: RAW (JSON), FORM_DATA, X_WWW_FORM_URLENCODED, BINARY, or GRAPHQL

---

restApi:get

Use GET to retrieve data from a remote API without modifying anything on the server. This is the most common action for reading resources, fetching lists, or querying search endpoints.

Parameters

GET requests use common parameters only. No request body is sent.

Example: Fetch a list of users from an external service

Field	Value
URL	https://api.example.com/v2/users
Headers	Accept: application/json
Query Params	status: active, limit: 50
Auth	Bearer Token with value from a global variable
Timeout	10000

What happens:

1. The node builds the full URL: https://api.example.com/v2/users?status=active&limit=50.
2. It adds the Accept header and the Authorization: Bearer <token> header.
3. It sends the GET request and waits up to 10 seconds for a response.
4. The parsed JSON response body is available for later steps.

---

restApi:post

Use POST to create new resources or submit data to an API. POST requests include a request body with the data to send.

Parameters

POST requests use common parameters plus body parameters.

Example: Create a new support ticket

Field	Value
URL	https://helpdesk.example.com/api/tickets
Headers	Content-Type: application/json
Auth	API Key named X-API-Key with value sk-abc123 sent in header
Body	{"subject": "Server alert", "priority": "high", "description": "CPU usage exceeded 90%"}
Content Type	RAW

What happens:

1. The node adds the API key header and content type header.
2. It sends the JSON body as a POST request.
3. The API returns the created ticket with its ID and status.
4. Later steps can reference the ticket ID from the response.

---

restApi:put

Use PUT to fully replace an existing resource. The request body should contain the complete updated resource.

Parameters

PUT requests use common parameters plus body parameters.

Example: Update a user profile

Field	Value
URL	https://api.example.com/v2/users/12345
Headers	Content-Type: application/json
Auth	Bearer Token
Body	{"name": "Jane Smith", "email": "jane.smith@example.com", "role": "admin"}
Content Type	RAW

What happens:

1. The node sends the full user object to the PUT endpoint.
2. The API replaces the existing user record with the provided data.
3. The response contains the updated user object.

---

restApi:patch

Use PATCH to partially update an existing resource. Unlike PUT, only the fields included in the body are modified.

Parameters

PATCH requests use common parameters plus body parameters.

Example: Update only a user's role

Field	Value
URL	https://api.example.com/v2/users/12345
Headers	Content-Type: application/json
Auth	Bearer Token
Body	{"role": "manager"}
Content Type	RAW

What happens:

1. The node sends only the changed field to the PATCH endpoint.
2. The API updates the role field while leaving all other user fields unchanged.
3. The response contains the updated user object.

---

restApi:delete

Use DELETE to remove a resource from the remote system. DELETE requests typically do not include a body.

Parameters

DELETE requests use common parameters only. No request body is sent.

Example: Remove a deactivated user

Field	Value
URL	https://api.example.com/v2/users/12345
Auth	Bearer Token
Timeout	15000

What happens:

1. The node sends a DELETE request to the user endpoint.
2. The API removes the user and returns a confirmation status.
3. The step succeeds if the server returns a 2xx status code.

---

Authentication Options

The auth object controls how the node authenticates with the target API. Choose the scheme that matches the API's requirements.

No Auth

No authentication is applied. Omit the auth object entirely or leave it empty. Use this for public endpoints that do not require credentials.

Basic Auth

Sends the username and password as a Base64-encoded string in the Authorization header.

Field	Type	Required	Description
type	string	Yes	Set to basic
username	string	Yes	The username
password	string	Yes	The password

Example:

Field	Value
type	basic
username	api-user
password	s3cret

The node sends the header: Authorization: Basic YXBpLXVzZXI6czNjcmV0.

Bearer Token

Sends a token in the Authorization header. This is the most common scheme for modern APIs that use JWT or opaque tokens.

Field	Type	Required	Description
type	string	Yes	Set to bearer
token	string	Yes	The bearer token value

Example:

Field	Value
type	bearer
token	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The node sends the header: Authorization: Bearer eyJhbGci....

API Key

Sends a named key-value pair either as a header or a query parameter. Many APIs use this as a lightweight authentication method.

Field	Type	Required	Description
type	string	Yes	Set to apiKey
key	string	Yes	The name of the key (e.g., X-API-Key)
value	string	Yes	The key value
addTo	string	No	Where to include the key: header (default) or queryParam

Example with header:

Field	Value
type	apiKey
key	X-API-Key
value	sk-live-abc123def456
addTo	header

Example with query parameter:

Field	Value
type	apiKey
key	api_key
value	sk-live-abc123def456
addTo	queryParam

When addTo is queryParam, the key and value are appended to the URL as a query parameter.

OAuth 2.0

Obtains an access token from an OAuth 2.0 authorization server before making the request. The node handles the token exchange automatically and refreshes expired tokens.

Field	Type	Required	Description
type	string	Yes	Set to oauth2
grantType	string	Yes	OAuth grant type: client_credentials, password, or authorization_code
tokenUrl	string	Yes	The token endpoint URL
clientId	string	Yes	The OAuth client ID
clientSecret	string	Yes	The OAuth client secret
scope	string	No	Space-separated list of requested scopes

Additional fields for the password grant type:

Field	Type	Required	Description
username	string	Yes	Resource owner username
password	string	Yes	Resource owner password

Example: Client Credentials flow

Field	Value
type	oauth2
grantType	client_credentials
tokenUrl	https://auth.example.com/oauth/token
clientId	my-app-id
clientSecret	my-app-secret
scope	read write

What happens:

1. The node sends a token request to the tokenUrl with the client credentials.
2. The authorization server returns an access token.
3. The node attaches the token as a Bearer token in the Authorization header.
4. If the token has expired, the node automatically requests a new one.

---

Pagination

For APIs that return results across multiple pages, the REST API node can automatically follow pagination and aggregate all results into a single response.

Pagination Parameters

Parameter	Type	Required	Description
paginationType	string	Yes	Pagination strategy: OFFSET, CURSOR, or LINK_HEADER
maxPages	integer	No	Maximum number of pages to fetch. Prevents runaway requests

OFFSET Pagination

Page-and-limit style pagination. The node increments the page number on each request.

Parameter	Type	Required	Description
pageParam	string	Yes	Query parameter name for the page number (e.g., page)
limitParam	string	Yes	Query parameter name for the page size (e.g., limit or per_page)

Example:

Field	Value
paginationType	OFFSET
pageParam	page
limitParam	per_page
maxPages	10

The node sends requests to ?page=1&per_page=25, then ?page=2&per_page=25, and so on until there are no more results or maxPages is reached.

CURSOR Pagination

Cursor-based pagination. The node extracts a cursor value from each response and passes it in the next request.

Parameter	Type	Required	Description
cursorParam	string	Yes	Query parameter name for the cursor (e.g., cursor or after)
cursorPath	string	Yes	JSON path to the next cursor value in the response (e.g., meta.next_cursor)

Example:

Field	Value
paginationType	CURSOR
cursorParam	after
cursorPath	pagination.next_cursor
maxPages	20

The node reads pagination.next_cursor from each response and passes it as ?after=<value> in the next request. Pagination stops when the cursor is empty or null.

LINK_HEADER Pagination

The node follows the next URL from the standard HTTP Link header. No additional parameters are required beyond paginationType and optionally maxPages.

Example:

Field	Value
paginationType	LINK_HEADER
maxPages	15

The node reads the Link header (e.g., <https://api.example.com/items?page=2>; rel="next") and follows the next URL automatically.

---

Settings

Additional behavior settings that affect how the request is handled:

Setting	Type	Default	Description
enableSSLVerification	boolean	true	Verify SSL certificates. Set to false for self-signed certificates in development environments
disableCookieJar	boolean	false	When true, cookies from the response are not stored or sent on subsequent requests
lowercaseHeaders	boolean	false	When true, all header names are normalized to lowercase
neverError	boolean	inherits saved request	Per-step override of the saved request's responseSettings.neverError. When true, an HTTP error status (4xx/5xx) does not fail the step — the response is returned normally so the workflow can inspect it

The neverError setting is evaluated per step. If you leave it unset, the value saved on the request (responseSettings.neverError) applies; setting it here overrides that saved value for this step only.

Response Format

optionDetails.responseFormat controls how the response body is typed in the step result:

Value	Result typing
AUTODETECT	Chooses the type from the response's Content-Type
JSON	Parses the body as JSON
TEXT	Returns the body as a plain string
XML	Parses the body as XML
BINARY	Returns the raw bytes

This is distinct from the connector-level responseType (json, text, binary) in the common parameters: responseType governs how the connector reads the response off the wire, while responseFormat governs how the returned result is typed for downstream steps.

---

Connection

The REST API node does not require a pre-configured connection. Authentication credentials are provided inline in the auth configuration object. However, you can use variable references that resolve from workflow variables or secrets stored in the Global Configurator.

For endpoints that require mutual TLS or custom CA certificates, set sslVerification to false or configure the JVM truststore at the platform level.

---

Output

Every action returns an ExecutionResponse object with the following fields:

Field	Type	Description
statusCode	integer	HTTP status code (e.g., 200, 201, 404)
reasonPhrase	string	HTTP status text (e.g., OK, Created, Not Found)
responseHeaders	object	Key-value pairs of response headers returned by the server
responseBody	any	Parsed response body. Format depends on the responseType setting: JSON object, plain text string, or binary data
responseSize	object	Size breakdown with headers (bytes), body (bytes), and total (bytes)
requestSize	integer	Total size of the outgoing request in bytes
totalTime	integer	Total response time in milliseconds, including connection, transfer, and parsing

Example output for a successful GET request:

{
  "statusCode": 200,
  "reasonPhrase": "OK",
  "responseHeaders": {
    "content-type": "application/json",
    "x-request-id": "abc-123"
  },
  "responseBody": {
    "users": [
      {"id": 1, "name": "Alice"},
      {"id": 2, "name": "Bob"}
    ]
  },
  "responseSize": {
    "headers": 245,
    "body": 1024,
    "total": 1269
  },
  "requestSize": 312,
  "totalTime": 187
}

When the HTTP status code indicates an error (4xx or 5xx), the step will fail and the response body is included in the error details for debugging.

---

Common Error Scenarios

Error	Status Code	Likely Cause	What to Check
Unauthorized	401	Missing, expired, or invalid credentials	Verify the auth configuration. For OAuth, confirm the token URL and client credentials are correct. For Bearer tokens, check that the token has not expired
Forbidden	403	Valid credentials but insufficient permissions	Confirm the authenticated user or application has the required role or scope for the endpoint
Not Found	404	Incorrect URL or the resource does not exist	Double-check the URL path and any resource IDs. Ensure the API version in the URL is correct
Rate Limited	429	Too many requests in a short period	Add a delay between requests or reduce the number of concurrent workflows calling the same API. Check the Retry-After header in the response
Server Error	500	The remote API encountered an internal error	This is not a workflow problem. Retry the request or contact the API provider. Check the response body for error details
Request Timeout	--	The server did not respond within the configured timeout	Increase the timeout value. Verify the API is reachable and not overloaded
SSL Certificate Error	--	The server's SSL certificate is untrusted, expired, or self-signed	For production APIs, ensure the certificate chain is valid. For internal or development APIs, set sslVerification to false
Connection Refused	--	The server is not accepting connections on the specified host and port	Verify the URL, check that the API service is running, and confirm there are no firewall or network restrictions

---

Best Practices

• Use global variables for URLs and tokens. Store base URLs, API keys, and tokens in Global Variables so they are easy to update without editing every workflow step.
• Set reasonable timeouts. The default 30-second timeout works for most APIs, but reduce it for fast endpoints and increase it for slow report-generation or file-download APIs.
• Handle rate limits. If an API enforces rate limits, space out requests or add retry logic in the workflow. Check the API documentation for rate limit headers.
• Use the right HTTP method. GET for reading, POST for creating, PUT for full replacement, PATCH for partial updates, DELETE for removal. Using the wrong method may cause unexpected results.
• Keep request bodies small. For large file uploads, use the BINARY or FORM_DATA content type rather than embedding large data in a JSON body.
• Verify SSL in production. Only disable SSL verification for internal development or testing environments. Always keep it enabled for production APIs.
• Store secrets securely. Never hard-code passwords, tokens, or API keys directly in the workflow. Use Global Configurator secrets or global variables instead.
• Test with a single request first. Before enabling pagination or running a workflow in production, test the API call with a single request to confirm the URL, headers, and authentication are correct.