--- title: Using the HTTP Request Native Action slug: using-the-http-request-native-action docTags: createdAt: 2025-08-11T11:13:48.000Z --- The **HTTP Request** native action in Swimlane Turbine allows orchestrators to interact with APIs, whether or not a pre-existing connector for the service exists. This action facilitates sending and receiving data to/from specific API endpoints, making it a vital tool for creating comprehensive playbooks with custom outputs and enhanced performance. **Required Inputs:** - **endpoint**: The URL address of the API endpoint (required) - **method**: The HTTP method to use (required, defaults to GET) The action supports dynamic URL path parameters using the `:variableName` syntax in the endpoint URL, which are replaced with actual values at runtime. Path parameters allow you to create reusable endpoint templates. For example, an endpoint like `https://api.example.com/users/:userId` can have the `userId` path parameter replaced dynamically. To configure path parameters, use the **Path Variables** tab in the action configuration (see the Path Variables Tab section below). Starting in **Turbine 26.2.0**, you can choose how the HTTP **response body** is parsed on the **Outputs** tab instead of relying only on **Content-Type** auto-detection. Use this when an API returns JSON with a missing or unusual content type, plain text or XML you will handle later, or binary content you need as a file attachment. ## Key Benefits - **Flexibility:** Supports multiple HTTP methods (GET, POST, PUT, and so on) to handle various API interactions. - **Customizable:** Allows for detailed configuration of authentication, parameters, headers, and body content to suit specific API requirements. - **Integration:** Easily integrates with third-party services, enhancing workflow automation. - **Error Handling:** Built-in options like retries and timeouts improve reliability and control over API interactions. - **Performance:** Streamlines the automation of tasks that require external data retrieval or updates, improving operational efficiency. ## Adding the HTTP Request Action To configure an HTTP Request, drag and drop the **HTTP Request** action from the Add Panel, then click **Configure**. Follow the steps below to complete the configuration. ## Request Method Select the desired request method from the drop-down. **GET** is the default request method. ## Authentication Tab On the **Authentication** tab, you can select the appropriate authentication type for your API request. The available types are: ## Parameters Tab To add query parameters to your HTTP Request, go to the **Parameters** tab and click **Add Parameter**. Enter key-value pairs for each parameter. Query parameters are appended to the URL as `?key=value&key2=value2`. **Note:** Parameters can be enabled or disabled individually, allowing you to conditionally include them in requests. ::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/TRcHpXsBk5O2mtwXlajds_http-parameters-tab.png" size="68" width="1736" height="867" darkWidth="1736" darkHeight="867" position="center" alt="HTTP Parameters Tab" showCaption="false"} ## Path Variables Tab Path variables (also called path parameters) allow you to dynamically replace parts of the URL path. In your endpoint URL, use the `:variableName` syntax (colon followed by the variable name) to define path parameters. For example, if your endpoint is `https://api.example.com/users/:userId/posts/:postId`, you can define `userId` and `postId` as path variables in the **Path Variables** tab and set their values dynamically. **Note:** The **Path Variables** tab may not be visible initially. It appears automatically when you use the `:variableName` syntax in your endpoint URL. **Example:** - Endpoint: `https://api.example.com/users/:userId` - Path Variable: `userId` with value `123` - Resulting URL: `https://api.example.com/users/123` **Multiple Path Parameters:** You can use multiple path parameters in a single endpoint: - Endpoint: `https://api.example.com/api/:version/users/:userId/posts/:postId` - Path Variables: - `version` with value `v1` - `userId` with value `123` - `postId` with value `456` - Resulting URL: `https://api.example.com/api/v1/users/123/posts/456` Path variables are useful for creating reusable endpoint templates that can be customized per request. They provide a cleaner alternative to building URLs with string concatenation. ## Headers Tab On the **Headers** tab, you can view auto-generated headers that will be included with your request at run-time. You can also add custom headers, such as *Content-Type*, to meet specific API requirements. ::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/XwoOLVDjgqvac3YBtQEMG_http-headers-tab.png" size="70" width="1418" height="698" darkWidth="1418" darkHeight="698" position="center" alt="HTTP Headers Tab" showCaption="false"} ## Body Tab The **Body** tab allows you to define the data sent in the request body. Available options include **None**, **JSON**, **X WWW FORM URL Encoded**, **Attachment**, and **Form Data**. The default option is **None**. **Body Types:** - **None**: No body is sent with the request (default for GET, HEAD, OPTIONS, DELETE methods) - **JSON**: Send JSON data with `Content-Type: application/json` header - **X WWW Form URL Encoded**: Send form-encoded data with `Content-Type: application/x-www-form-urlencoded` header - **Attachment**: Send a file attachment with `Content-Type: application/octet-stream` header - **Form Data**: Send multipart form data with `Content-Type: multipart/form-data` header (useful for file uploads with additional fields) ::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/4gZI6qQ7Quk9e1lildoiN_http-body-tab.png" size="68" width="1415" height="665" darkWidth="1415" darkHeight="665" position="center" alt="HTTP Body Tab" showCaption="false"} ## Settings Tab In the **Settings** tab, you can configure request settings: - **Proxy**: Configure a proxy by selecting **Create New Asset** or choosing an existing proxy asset from the list. Proxy settings are applied via assets. - **Enable SSL certificate verification**: Toggle to enable or disable SSL/TLS certificate verification (default: enabled). **Warning:** Disabling certificate verification reduces security and should only be used in development environments or when dealing with self-signed certificates. - **Follow Redirects**: Automatically follow HTTP redirects (default: enabled) - **Allow Unsafe Legacy Renegotiation**: Allow unsafe legacy TLS renegotiation (default: disabled). Only enable if required by legacy systems. **Security Note:** Always enable SSL certificate verification in production environments to protect against man-in-the-middle attacks. ::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/bWrOKqaFg8sO6H6oog66o_http-settings-tab.png" size="70" width="1418" height="666" darkWidth="1418" darkHeight="666" position="center" alt="HTTP Settings Tab" showCaption="false"} ## Outputs Tab The **Outputs** tab allows you to promote action outputs for use elsewhere in the playbook. You can also mark data as sensitive if required by clicking the ellipsis icon and **Mark Sensitive**. Promoted outputs appear in the **Promoted Playbook Outputs** section. To remove a promoted output, click the **Remove** button next to the promoted output. ### Payload Format Options On the **Outputs** tab, under **Additional Options**, select how Turbine parses the HTTP **response body** into `$actions..result.body`. The radio options are **Auto-detect**, **Body as JSON**, **Body as Raw Text**, and **Body as File Attachment**. This setting controls response parsing only; it does **not** change request headers or the **Content-Type** sent to the API. | Option | When to Use | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Auto-detect** | Default. Turbine infers parsing from the response **Content-Type** header (same behavior as before 26.2.0). Existing HTTP Request actions keep this setting. | | **Body as JSON** | Always parse the response body as JSON, even when **Content-Type** is not `application/json`. Use when an API returns JSON with an unusual or missing content type. **Body as JSON** supports JSON only; use **Body as Raw Text** for XML, RSS, or other non-JSON text. If the response body is empty, **body** is not set. | | **Body as Raw Text** | Keep the full response body as a string without JSON parsing. Use for XML, HTML, or plain text you will parse in a later action. | | **Body as File Attachment** | Upload the response body as a file attachment. The **body** output contains file metadata (such as **file** and **file\_name**) you can pass to other actions. Use for binary downloads such as PDF or image files. | :::hint{type="info"} Use the **Test** tab to confirm how each format parses a response before you save the action. After you change a payload format option on **Outputs**, open the **Test** tab and run the test again — the selected format applies to the test run immediately. Click **Apply** on the action dialog when you are ready to save the format to the playbook. ::: ### Test the Selected Format | Step | Action | | ---- | ---------------------------------------------------------------------------- | | 1 | On **Outputs**, under **Additional Options**, select a payload format option | | 2 | Open the **Test** tab and run the test against your endpoint | | 3 | Review the response **body** shape in the test results | | 4 | Click **Apply** to persist the format on the HTTP Request action | Starting in **Turbine 26.2.0**, changing the format on **Outputs** updates the **Test** tab without clicking **Apply** first. **Apply** saves the setting to the playbook for production runs. ## Retry Mechanism The **Retry** option allow for greater control over HTTP requests, ensuring reliability and efficiency in automation workflows. ### Retry Configure retry criteria to handle temporary failures. You can specify the number of retries and the delay between retries. Retries are useful for handling transient network issues or temporary server errors. **Example:** Set up retries with exponential backoff for API calls that may occasionally fail due to network issues. **Note:** Retries are configured at the playbook action level, not within the HTTP Request action itself. ## Handling HTTP Responses The HTTP Request action returns a response object that includes: - **status\_code**: The HTTP status code (for example, 200, 404, 500) - **status\_reason**: The HTTP status reason phrase (for example, "OK", "Not Found", "Internal Server Error") - **headers**: Response headers as a record of string or string array values - **body**: The response body. Shape depends on the payload format option on the **Outputs** tab (object when parsed as JSON, string when raw text, file metadata when uploaded as attachment) ### Accessing Response Data You can access response data in subsequent actions using expressions: - `$actions.actionName.result.status_code` - Access the status code - `$actions.actionName.result.status_reason` - Access the status reason - `$actions.actionName.result.headers` - Access response headers - `$actions.actionName.result.body` - Access the response body - `$actions.actionName.result.body.propertyName` - Access nested properties in JSON responses ### Common Response Codes - **200 OK:** Request was successful. - **201 Created:** Resource was successfully created (common for POST requests). - **400 Bad Request:** Client-side error; check the request syntax, headers, or body format. - **401 Unauthorized:** Authentication error; verify credentials and authentication method. - **403 Forbidden:** Access denied; verify permissions. - **404 Not Found:** Resource not found; check the URL and path variables. - **500 Internal Server Error:** Server-side error; consider retrying or alerting. - **502 Bad Gateway:** Invalid response from upstream server. - **503 Service Unavailable:** Service temporarily unavailable; consider retrying. ### Error Handling When an HTTP request fails, the action returns an error object. There are two types of errors: - **HTTP API Error**: Contains the HTTP response (status\_code, headers, body) when the server responds with an error status code - **HTTP Code Error**: Contains a code error (name, message) when the request fails due to network issues, timeouts, or other non-HTTP errors Use conditional logic to check the response status code and handle errors appropriately: **Example:** Check if the status code is 200 before processing the response, otherwise log the error or retry the request. ## Advanced Use Cases ### Example 1: Sending Data with Authentication **Scenario:** Send a JSON payload to an API endpoint with Bearer Token authentication. 1. Select the **POST** method. 2. In the Authentication tab, choose **Bearer Token** and provide the token. 3. Configure the Body tab with **JSON** and define the payload. ### Example 2: Handling Query Parameters **Scenario:** Retrieve specific data from an API by passing query parameters. 1. Select the **GET** method. 2. Add key-value pairs in the Parameters tab. ### Example 3: Using Path Parameters **Scenario:** Access a specific user's data using a path parameter in the endpoint URL. 1. Enter an endpoint URL with a path parameter using colon syntax: `https://api.example.com/users/:userId` 2. The **Path Variables** tab will appear automatically. 3. In the Path Variables tab, define the `userId` variable and set its value (for example, `123`). 4. The resulting URL will be: `https://api.example.com/users/123` ### Example 4: Handling Paginated Responses **Scenario:** Many APIs paginate large datasets. Here is how you can handle this scenario: 1. Send the initial request and store the response. 2. Check for a pagination token or next URL in the response. 3. Repeat the request using the next URL or token until all pages are retrieved. ## Security Considerations When interacting with APIs, it is crucial to follow best practices to ensure security: - **Validate SSL Certificates:** Always enable SSL certificate verification to protect against man-in-the-middle attacks. - **Secure Credentials:** Use environment variables or secure vaults to manage sensitive information like API keys or tokens. - **Limit Data Exposure:** Only promote outputs that are necessary, and mark sensitive data appropriately to prevent unintentional exposure. ## Troubleshooting - **Request Fails with "endpoint is required":** Ensure you have provided an endpoint URL in the action configuration. The endpoint field is required. - **Request Fails with "method is required":** Ensure you have selected an HTTP method. The method defaults to GET but must be explicitly set. - **Request Fails with 401 Unauthorized:** Ensure the correct authentication method and credentials are provided. Verify that tokens or API keys have not expired. - **Request Fails with 400 Bad Request:** Check that: - The request body format matches the API's expectations (JSON vs form-encoded) - Required headers are included (especially Content-Type) - Query parameters and path variables are correctly formatted - **Path Variables Not Replaced:** Ensure path variables are defined in the Path Variables tab and that the endpoint URL uses the `:variableName` syntax (colon followed by the variable name). Variable names are case-sensitive and must match exactly between the endpoint URL and the Path Variables tab. If the Path Variables tab is not visible, add a path parameter using the `:variableName` syntax in your endpoint URL (for example, `https://api.example.com/users/:userId`). - **Unexpected Response Format:** Verify the API documentation and ensure your headers and body match the expected format. Check the response **Content-Type** header. On the **Outputs** tab, under **Additional Options**, select **Body as JSON** when the API omits **Content-Type**, or **Body as Raw Text** when JSON parsing fails. - **Test Tab Shows the Wrong Body Shape:** On **Outputs**, select the format you want, then open the **Test** tab and run the test again. The test uses the selected format immediately; you do not need to click **Apply** first to preview parsing. Click **Apply** to save the format to the playbook action. - **Body as JSON Test or Run Fails:** The response must be valid JSON when **Body as JSON** is selected. Use **Body as Raw Text** for XML, RSS, or other non-JSON content. - **Response Body Is Empty or Wrong Type:** On the **Outputs** tab, under **Additional Options**, choose a format other than **Auto-detect**. Use **Body as File Attachment** when the response is binary and you need a file reference for a later action. - **Timeout Issues:** Increase the timeout settings at the action level or check network stability. Consider using retry logic for transient network issues. - **SSL Certificate Errors:** If you encounter SSL certificate errors, verify that: - SSL certificate verification is enabled (recommended) - The server's certificate is valid and trusted - Only disable certificate verification in development environments - **Attachment Not Sent:** When using the Attachment body type, ensure: - The file reference is correct - For arrays of files, use an expression to select a specific file (for example, `$inputs.files[0]`) - Attachments are not used during test runs (not supported) ## Best Practices - **Use Secure Authentication:** Always prefer secure methods like OAuth 2.0 or Bearer Tokens over Basic Auth. Store sensitive credentials in environment variables or secure assets rather than hardcoding them. - **Validate Required Fields:** Always ensure the endpoint and method are configured. Use path variables for dynamic endpoints rather than string concatenation. - **Handle Errors Gracefully:** Use conditional logic to check response status codes and handle errors appropriately. Consider implementing retry logic for transient failures. - **Test API Endpoints:** Validate API endpoints and configurations in a testing environment before deploying them in production. Test with various response scenarios including success and error cases. - **Use Descriptive Variable Names:** Clearly label your parameters, headers, and path variables for easy identification and debugging. - **Enable SSL Verification:** Always enable SSL certificate verification in production environments. Only disable it in development when necessary. - **Structure Request Bodies Properly:** Match the Content-Type header with the body format (JSON, form-encoded, and so on) as expected by the API. - **Use Path Variables for Dynamic URLs:** Instead of building URLs with string concatenation, use path variables with the `:variableName` syntax (colon followed by the variable name) for cleaner, more maintainable code. Define the path variables in the Path Variables tab to set their values dynamically. - **Monitor Response Sizes:** Be aware of response size limits. Large responses may need to be handled differently or paginated. - **Document API Contracts:** Document the expected request format, headers, and response structure for your team to ensure consistency. ## Use Cases For examples of how to use the HTTP Request action, see the [HTTP Request use case](#).