Calling Etlworks Built-in APIs

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:

1. Call the Etlworks Authentication API with your username and password.

2. 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)

1. Generate non-expiring API key.

2. 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.