Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hypha-docs.plinqx.app/llms.txt

Use this file to discover all available pages before exploring further.

The HTTP node allows you to make HTTP requests to any external API directly within your flow, with support for dynamic URLs, headers, query parameters, request bodies, and Vault-based authentication.

​
Overview

HTTP nodes enable:
  • Dynamic HTTP Requests: Make GET, POST, PUT, PATCH, DELETE requests
  • Expression Support: Use expressions in URLs, headers, query params, and body
  • Vault Authentication: Automatically apply credentials from Vault
  • Success/Error Routing: Separate output paths for success (2xx) and error (4xx/5xx) responses
  • Retry Logic: Configurable retry with exponential backoff
  • Response Access: Store and access response data in subsequent nodes

​
How It Works

1

Configure Request

Set HTTP method, URL, headers, query parameters, and body.
2

Resolve Expressions

HTTP node resolves all expressions in URL, headers, params, and body.
3

Apply Authentication

If Vault credential is configured, applies authentication automatically.
4

Execute Request

Makes HTTP request with retry logic if configured.
5

Route by Status

Routes to success path (2xx) or error path (4xx/5xx) based on response status.
6

Store Output

Response data available to subsequent nodes via output variable.

​
Configuration

​
Basic Configuration

HTTP Method:
  • GET, POST, PUT, PATCH, DELETE
URL:
  • Full URL with optional expression support
  • Example: https://api.example.com/users/{{input.userId}}
API Name:
  • Unique identifier for this step
  • Used in expressions: {{http_step_name.output}}

​
Headers

Add custom headers with expression support: 
Authorization: Bearer {{vault.token}}
Content-Type: application/json
X-Request-ID: {{$uuid}}
Header Features:
  • Enable/disable individual headers
  • Expression support in header values
  • Automatic Content-Type handling for request body

​
Query Parameters

Add query parameters with expression support: 
userId={{input.userId}}
page={{steps.previous.output.page}}
limit=10
Query Parameter Features:
  • Enable/disable individual parameters
  • Expression support in parameter values
  • Automatically URL-encoded

​
Request Body

Configure request body for POST, PUT, PATCH, DELETE methods: Content Types:
  • application/json - JSON format
  • application/x-www-form-urlencoded - Form data
  • text/plain - Plain text
Body Examples: JSON Body: 
{
  "name": "{{input.name}}",
  "email": "{{input.email}}",
  "metadata": {
    "source": "flow",
    "timestamp": "{{$now}}"
  }
}
Form URL Encoded: 
name={{input.name}}&email={{input.email}}

​
Authentication

Select a Vault credential to automatically apply authentication: Supported Auth Types:
  • API Key: Applied as X-API-Key header
  • Bearer Token: Applied as Authorization: Bearer <token>
  • Basic Auth: Applied as Authorization: Basic <credentials>
  • OAuth2 Client Credentials: Automatically retrieves and applies access token
  • OAuth2 Authorization Code: Uses stored access token
Vault credentials are automatically refreshed for OAuth2 flows. The HTTP node handles token refresh transparently.

​
Output Variable

Store the HTTP response in a variable for use in subsequent nodes: Variable Name: httpResult Response Structure: 
{
  "statusCode": 200,
  "statusText": "OK",
  "headers": { "content-type": "application/json" },
  "body": { "id": 123, "name": "Example" },
  "duration": 245,
  "success": true
}
Access in Expressions: 
{{httpResult.body.id}}
{{httpResult.statusCode}}
{{httpResult.headers['content-type']}}

​
Advanced Options

Timeout:
  • Default: 30,000ms (30 seconds)
  • Maximum time to wait for response
Retry Policy:
  • Max Attempts: Number of retry attempts (default: 1, no retry)
  • Backoff (ms): Delay between retries with exponential backoff
Retries only occur for 5xx server errors or network errors. 4xx client errors are not retried.

​
Success and Error Routing

HTTP nodes have two output paths: Success Path (2xx):
  • Followed when response status is 200-299
  • Use for normal processing
Error Path (4xx/5xx):
  • Followed when response status is 400-599
  • Use for error handling
Always connect both success and error paths to handle all possible outcomes. Unhandled errors will cause the flow to fail.

​
Expression Support

HTTP nodes support expressions in all fields: URL Expressions: 
https://api.example.com/users/{{input.userId}}/posts/{{steps.fetch_user.output.postId}}
Header Expressions: 
Authorization: Bearer {{vault.accessToken}}
X-User-ID: {{steps.start.output.userId}}
X-Request-ID: {{$uuid}}
Query Parameter Expressions: 
userId={{input.userId}}
page={{steps.pagination.output.currentPage}}
limit={{input.pageSize}}
Body Expressions: 
{
  "user": {
    "id": "{{steps.start.output.userId}}",
    "name": "{{steps.start.output.userName}}"
  },
  "timestamp": "{{$now}}",
  "metadata": "{{steps.previous.output}}"
}

​
Response Structure

HTTP node output includes: 
{
  "statusCode": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json",
    "x-request-id": "abc123"
  },
  "body": {
    "id": 123,
    "name": "Example"
  },
  "duration": 245,
  "success": true,
  "error": null
}
Error Response: 
{
  "statusCode": 404,
  "statusText": "Not Found",
  "headers": {},
  "body": { "error": "Resource not found" },
  "duration": 120,
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

​
Use Cases

API Integration

Integrate with external REST APIs

Webhook Callbacks

Send callbacks to external systems

Data Fetching

Fetch data from external services

Service Orchestration

Orchestrate calls to microservices

​
Examples

​
Example 1: Fetch User Data

Configuration:
  • Method: GET
  • URL: https://api.example.com/users/{{input.userId}}
  • Headers: Authorization: Bearer {{vault.apiToken}}
  • Output Variable: userData
Success Path: 
{{userData.body.name}}
{{userData.body.email}}

​
Example 2: Create Resource

Configuration:
  • Method: POST
  • URL: https://api.example.com/resources
  • Headers: Content-Type: application/json
  • Body:
{
  "name": "{{input.name}}",
  "type": "{{input.type}}",
  "metadata": {{steps.transform.output}}
}
  • Vault Credential: API Key
  • Output Variable: createdResource

​
Example 3: Update with Retry

Configuration:
  • Method: PUT
  • URL: https://api.example.com/users/{{input.userId}}
  • Body: {{steps.prepare_update.output}}
  • Retry Policy:
    • Max Attempts: 3
    • Backoff: 1000ms
  • Output Variable: updateResult

​
Best Practices

Use Expressions

Use expressions for dynamic URLs and parameters instead of hardcoding values

Handle Errors

Always connect the error path to handle failures gracefully

Set Timeouts

Configure appropriate timeouts based on expected response times

Use Vault

Store credentials in Vault instead of hardcoding in flows

Retry Wisely

Only enable retries for idempotent operations (GET, PUT, DELETE)

Log Responses

Use LOG nodes after HTTP calls to debug responses
Avoid retrying non-idempotent operations (POST) unless the API supports idempotency keys. Retrying POST requests can create duplicate resources.

​
Error Handling

HTTP nodes handle errors gracefully: Network Errors:
  • Connection refused
  • Timeout
  • DNS resolution failure
HTTP Errors:
  • 4xx: Client errors (bad request, unauthorized, not found)
  • 5xx: Server errors (internal server error, service unavailable)
Error Response: 
{
  "statusCode": 0,
  "statusText": "Network Error",
  "success": false,
  "error": {
    "code": "ECONNREFUSED",
    "message": "Connection refused"
  }
}

​
Next Steps

Transform Node

Transform HTTP response data

TRY Node

Handle HTTP errors with try/catch

Validate Node

Validate HTTP response structure

Vault

Learn about Vault credential management