Overview
Etlworks provides built-in API endpoints that can be called from third-party applications, tools like Postman, Etlworks Flows, or directly in Explorer. This guide explains how to authenticate and structure API requests.
Base URL and Endpoint Path
Every API request is made to a full URL constructed as:
https://<etlworks-host>:<port>/<ENDPOINT_PATH>
-
<etlworks-host> is the hostname of your Etlworks instance.
-
<port> is optional. Use it if your instance is not running on port 443 (HTTPS) or 80 (HTTP).
-
<ENDPOINT_PATH> is the relative path of the API you are calling.
Example:
To run a flow with ID 1234 on a cloud instance:
https://app.etlworks.com/rest/v1/flows/1234/run
If you’re running Etlworks on-prem at etlworks.internal.local on port 8080:
https://etlworks.internal.local:8080/rest/v1/flows/1234/run
URL Encoding
If the API path includes dynamic parameters or query strings, you must ensure that any special characters (spaces, slashes, etc.) are URL-encoded.
Example:
https://etlworks.internal.local:8080/rest/v1/flows/My%20Flow/run
You can use any standard URL encoder (e.g., in Postman or code) to do this automatically.
Authentication
All Etlworks API requests must include a valid JWT token in the Authorization header.
Option 1: Short-lived Access Token
There are two ways to obtain a token:
-
Call the Etlworks Authentication API with your username and password.
-
Use the returned access token in the Authorization header:
Authorization: Bearer <access_token>
These tokens expire after ~10 minutes.
Option 2: API Key (Non-expiring)
-
Use the API key just like the access token:
Authorization: Bearer <api_key>
This method is preferred for long-running integrations.
Making API Calls with Postman
Step 1. Get or generate your token.
Use either an access token or API key as described above.
Step 2. Set up the request
-
Method: Select the correct HTTP method (e.g., POST, GET)
-
URL: Enter the fully qualified URL (base_url/ENDPOINT_PATH)
-
If the request requires parameters, ensure they are URL-encoded
Step 3. (Optional) Add request body
If the endpoint requires a payload:
-
Go to the Body tab
-
Select raw → JSON
-
Enter your JSON payload
Step 4. Add headers
-
Go to the Headers tab
-
Add: Content-Type: application/json
Step 5. Authorize the request
-
Go to the Authorization tab
-
Choose Bearer Token
-
Paste your token (JWT or API key)
Step 6. Send the request
Calling Etlworks API from Flows
Step 1. Create an Etlworks API Connection.
If you need to capture the response from API call
Step 2. Create a source-to-destination Flow, where the source is a web service and the destination is anything. The source Connection needs to be the Etlworks API Connection created in Step 1.
If you don't need to capture the response from API call
Step 2. Use Call HTTP endpoint flow type to call Etlworks API. Use connection created in Step 1.
Calling API from Explorer
Step 1. Navigate to Etlworks API connection. Assign JSON format.
Step 2. Expand the connection and select the endpoint.
Step 3. Click Raw Data button.
Comments
0 comments
Please sign in to leave a comment.