Back to Step Functions

apiRequest

Advanced

Executes HTTP requests to external APIs with comprehensive configuration options including authentication, headers, body formatting, and file handling.

Table of Contents

overview

The apiRequest function enables Vibes to interact with external systems and services through HTTP requests. This powerful function supports complex request configurations, multiple authentication methods, file uploads, and various data formats.

Execute HTTP requests to external APIs with comprehensive configuration options including authentication, headers, body formatting, and file handling.

Powerful Integration: This function provides the foundation for integrating Vibes with virtually any external system or service, enabling powerful workflow automation that spans multiple platforms and technologies.

input_parameters

ParameterTypeRequiredDescription
endpointstringThe complete URL for the API request
methodstringOptionalHTTP method: GET, POST, PUT, PATCH, DELETE (default: GET)
authobjectOptionalAuthentication configuration
headersobject/arrayOptionalCustom headers for the request
bodyobjectOptionalEmail content (supports HTML formatting)
maxResponseSizenumberOptionalMaximum response size in bytes (default: 50MB)

Output Format

The queryKnowledgebase function returns structured document entries with citation information and content excerpts.

Return Format Example

Authentication Types

The apiRequest function supports multiple authentication methods to work with different API requirements:

Bearer Token

Standard bearer token authentication for OAuth and API tokens

Basic Authentication

HTTP Basic authentication using username and password

API Key

API key authentication with custom header configuration

OAuth2

OAuth2 token authentication for secure API access

Custom Headers

Custom authentication headers for specialized requirements

Headers and Body Configuration

Header Configuration

Headers can be configured using either object or array format to meet different API requirements:

Object Format

Array Format

Body Configuration

The function supports multiple body formats for different API requirements:

JSON Body

Standard JSON content for REST APIs

Form Data (URL-encoded)

URL-encoded form data for traditional web forms

Multipart Form Data (with files)

Multipart form data with file upload support

File Handling

The apiRequest function provides sophisticated file handling capabilities for uploading documents, images, and other file types:

File Upload Support

  • • Automatically detects when File objects are present in request data
  • • Converts to multipart/form-data encoding when needed
  • • Supports multiple file uploads in a single request
  • • Handles file metadata (name, size, type) appropriately

File Processing Contexts

  • • Multipart: Files sent as-is for form uploads
  • • JSON/Base64: Files converted to base64 for JSON APIs
  • • Metadata: Only file information sent (name, size, type)

File Considerations

  • • Consider file type restrictions and validation
  • • Validate file sizes before upload
  • • Handle upload failures gracefully
  • • Test with various file formats

Usage Examples

Simple GET Request

Basic data retrieval from an external API:

Basic Data Retrieval

POST Request with JSON Body

Creating new resources with JSON data:

User Creation API

File Upload with Authentication

Uploading files with API key authentication:

Document Upload Service

Complex API Integration

Advanced payment processing with multiple headers and authentication:

Payment Processing API

Dynamic Field Configuration

Using dynamic field types for flexible data submission:

Flexible Data Submission

Error Handling

The apiRequest function provides comprehensive error handling for various scenarios:

HTTP Error Responses

  • • 4xx Client Errors: Authentication, validation, or request format issues
  • • 5xx Server Errors: External service unavailability or processing errors
  • • Network Errors: Timeout, connection, or DNS resolution issues

Response Size Management

  • • Automatic truncation of oversized responses
  • • Configurable size limits per request
  • • Warning notifications for large responses
  • • Protection against memory issues

Common Error Scenarios

Authentication Failures

Status: 401 - Invalid or expired authentication credentials
Status: 403 - Insufficient permissions for the requested resource

Request Format Issues

Status: 400 - Invalid request format or missing required fields
Status: 422 - Valid format but unprocessable content

Response Size Errors

Response size exceeded maximum limit (50MB)
Solution: Use pagination or filtering parameters

Best Practices

Authentication & Security

Protect API credentials and use appropriate authentication methods for your security requirements.

  • Store API credentials securely using global variables or environment variables
  • Use the appropriate authentication method for your API's security requirements
  • Implement token refresh logic for OAuth flows when needed

Error Handling

Implement proper error handling for background operations since users won't see failure messages.

  • Handle HTTP error responses (4xx, 5xx) with appropriate retry logic
  • Implement retry logic with condition-based limits
  • Validate API response formats before processing in subsequent steps

Performance Optimization

Optimize API requests for better performance and resource usage.

  • Set appropriate maxResponseSize limits for large APIs
  • Use pagination when dealing with large datasets
  • Monitor response sizes and processing times for optimization

data_handling

Ensure reliable data processing and variable management.

  • Validate input data before sending API requests
  • Handle null or empty responses gracefully in workflow logic
  • Use structured variable names for complex API responses

Related Functions

These functions work well with apiRequest for building comprehensive API integration workflows:

aiProcessinghandleConditionalsendEmail