API Call Node
Integration & Connectivity Technical Deep Dive
The API Call Node serves as a critical integration point within automated workflows, enabling robust communication with external HTTP/HTTPS endpoints. This document details its technical specifications, including input/output data contracts, configuration parameters, and error handling mechanisms. Understanding these specifications is paramount for seamless integration and reliable workflow orchestration.
Purpose and How the Node Works
The API Call Node facilitates the invocation of any external HTTP/HTTPS endpoint within a workflow, passing the response (or failure details) to downstream nodes.
Input Resolution:
$input: Output of the previous node.
$secret: Secrets from the Uptiq.ai vault.
These can be referenced in any templatable field (e.g., URL, headers, body).
Example: https://api.example.com/users/$input.userId or Authorization: Bearer $secret.token
Request Assembly: Endpoint, query parameters, headers, and body are composed from the node's configuration.
Execution: The node issues a blocking HTTP call; it always waits for completion. The behavior does not change between synchronous and asynchronous workflow modes.
Response Handling:
Success: Emits data payload.
Failure: Fills error, statusCode, statusText; data may be null.
Configuration Schema
The API Call Node's behavior is defined by the following configuration parameters:
Field
Type
Required
Description
endpoint
string
✅
Absolute URL of the external HTTP/HTTPS endpoint.
method
GET
POST
PUT
headers
object<string,string>
Extra request headers (key-value pairs).
params
object<string,string
string[]>
data
string
object
buffer
dataFormat
key-value
raw
rawDataFormat
json
text
binary
auth
object
Authentication helper object. See schema below.
Auth Helper Schemas:
basic:
JSON
{
"username": "...",
"password": "..."
}
bearer:
JSON
{
"token": "..."
}
apiKey:
JSON
{
"headers": {
"X-Client-ID": "...",
"X-Client-Secret": "..."
}
}
Supports multiple header/value pairs.
Output Schema
Upon completion, the API Call Node emits a structured output containing the response details.
Field
Type
Required
Description
data
any
null
statusCode
number
✅
HTTP status (0 on network error).
statusText
string
✅
Reason phrase (e.g., "OK", "Conflict").
headers
object<string,string>
✅
Response headers (lower-cased keys).
error
string
null
Examples
Success Example
Configuration:
JSON
{
"endpoint": "https://api.example.com/invoices",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"X-Client-ID": "$secret.clientId",
"X-Client-Secret": "$secret.clientSecret"
},
"params": {
"expand": ["payments", "customer"]
},
"data": {
"amount": 1000,
"currency": "USD"
},
"dataFormat": "raw",
"rawDataFormat": "json"
}
Output:
JSON
{
"data": {
"id": "inv_456",
"amount": 1000,
"status": "issued"
},
"statusCode": 201,
"statusText": "Created",
"headers": {
"content-type": "application/json",
"date": "Fri, 11 Jul 2025 11:30:00 GMT"
},
"error": null
}
Failure Example (Duplicate Invoice)
Output:
JSON
{
"data": {
"error": {
"type": "duplicate_request",
"message": "Invoice already exists"
}
},
"statusCode": 409,
"statusText": "Conflict",
"headers": {
"content-type": "application/json",
"date": "Fri, 11 Jul 2025 11:31:00 GMT"
},
"error": "HTTP_ERROR"
}
Multi-value Query Parameter
Configuration:
JSON
{
"params": {
"dataId": ["123", "234", "4343"]
}
}
Generates: ?dataId=123&dataId=234&dataId=4343
Single-Node Test API
For testing a node in isolation (e.g., via the UI "Test" button or a dedicated API), the following endpoint is used:
Path: /skill-runtime/workflows/nodes/APICall/execute
Method: POST
Purpose: Execute one node in isolation.
Request Body:
JSON
{
"nodeType": "API_CALL",
"config": { /* same as Section 2.2 */ },
"input": { /* input for the node, e.g., from previous node's output */ }
}
Error Handling Recap
Network/TLS/DNS Errors:
statusCode: 0
statusText: "" (empty string)
error: System message (e.g., "NETWORK_ERROR")
data: null
HTTP Errors (Status Code >= 400):
statusCode: Echoes the HTTP status code (e.g., 400, 401, 404, 500)
statusText: Echoes the HTTP status text (e.g., "Bad Request", "Unauthorized", "Not Found", "Internal Server Error")
error: "HTTP_ERROR"
data: Contains the parsed response body from the external service (if any).
Security Notes
Inject Secrets via $secret: NEVER hard-code sensitive information (API keys, authorization tokens) directly in the node configuration. Always use the $secret variable syntax to inject these values from the Uptiq.ai vault.
Engine Logs Redaction: The Mattr engine logs are designed to redact any field marked as sensitive, including API Key and Authorization headers, to prevent sensitive data leakage in internal logs. These security notes are for development best practices.
Last updated