Quickstart

Go from zero to your first API call in under 5 minutes. This guide walks you through authentication, tool discovery, chat, streaming, and sessions.

Prerequisites

An Etlworks Integrator account with AI features enabled
Admin access to generate an API key
curl installed (comes with macOS, Linux, and Windows 10+)
Optional: jq for pretty-printing JSON responses
Optional: Python 3.6+ with the requests library for the Python client

Step 1: Get your API key

Open user settings

Log in to your Etlworks instance and navigate to Settings → Users.
Select the user

Click the user who will own the API key. This can be your own account or a dedicated API user. The user must have the API User role or API key access must be enabled in system settings.
Generate the key

In the user edit dialog, go to the API Key section and click Generate API Key. You can set an optional expiration (or leave it permanent). Copy the key immediately — it won't be shown again.

Keep your key secure

Treat your API key like a password. Store it in environment variables or a secrets manager — never commit it to source control.

Set the key as an environment variable for the rest of this tutorial:

Shell

export ETLWORKS_URL="https://your-instance.etlworks.com"
export ETLWORKS_API_KEY="your-api-key-here"

Step 2: Your first API call

Let's verify your setup by listing the available agent tools:

Shell

curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api/tools" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" | jq .

You should see a response listing all available tools:

JSON

{
  "tools": [
    {
      "name": "search_knowledge_base",
      "description": "Search the knowledge base for articles, documentation, and support tickets",
      "parameters": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] },
      "agentic": false
    },
    {
      "name": "host_cli",
      "description": "Execute a CLI command on the Etlworks host",
      "parameters": { "type": "object", "properties": { "command": { "type": "string" } }, "required": ["command"] },
      "agentic": true
    }
  ],
  "count": 7
}

401 Unauthorized?

Double-check that your API key is correct and that the user has API access enabled. Also verify the base URL includes the correct protocol (https://).

Step 3: Explore the tools

Now let's call a tool directly. The search_knowledge_base tool searches Etlworks documentation, KB articles, and support tickets:

Shell

curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api/tools/search_knowledge_base/execute" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how to create a REST API connection"}' | jq .

The response contains the raw tool output — the same data the AI agent sees when it calls this tool internally:

JSON

{
  "tool": "search_knowledge_base",
  "result": "Based on the knowledge base:\n\n## Creating a REST API Connection\n\nTo create a REST API connection...",
  "success": true
}

Here's a quick reference of all tools you can call:

Tool name	Billing	What it does
`search_knowledge_base`	Free	Search KB articles, docs, templates, and support tickets
`search_templates`	Free	Search flow and connection templates
`create_support_ticket`	Free	Create a Zendesk support ticket
`host_list_commands`	Billed	List available CLI commands
`host_cli`	Billed	Execute a CLI command
`import_template`	Billed	Import a flow or connection template

Step 4: Chat with the agent

Instead of calling tools manually, you can send a natural language message to the AI agent. It will automatically choose which tools to use and compose a helpful response:

Shell

curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api/chat" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I set up a daily sync from a REST API to PostgreSQL?"}' | jq .

JSON

{
  "response": "To set up a daily sync from a REST API to PostgreSQL, follow these steps:\n\n1. **Create a REST API connection** ...\n2. **Create a PostgreSQL connection** ...\n3. **Create a flow** ...\n4. **Schedule the flow** ...",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tools_used": ["search_knowledge_base"],
  "usage": {
    "prompt_tokens": 1842,
    "completion_tokens": 456,
    "model": "gpt-4.1"
  }
}

The agent searched the knowledge base, found relevant articles, and composed a step-by-step answer.

Step 5: Streaming responses

For real-time display, use the streaming endpoint. Responses arrive as Server-Sent Events (SSE) — tokens stream in as they're generated:

Shell

curl -sN "$ETLWORKS_URL/rest/v1/ai-agent/api/chat/stream" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are the main features of Etlworks Integrator?"}'

You'll see events stream in real time:

HTTP

data: {"type":"session","session_id":"a1b2c3d4..."}

data: {"type":"phase","phase":"thinking","message":"Reviewing your request..."}

data: {"type":"tool_start","tool":"search_knowledge_base","message":"Searching the knowledge base..."}

data: {"type":"tool_end","tool":"search_knowledge_base"}

data: {"type":"token","content":"Etlworks "}

data: {"type":"token","content":"Integrator "}

data: {"type":"token","content":"is "}

data: {"type":"token","content":"a "}

data: {"type":"usage","prompt_tokens":1200,"completion_tokens":350,"model":"gpt-4.1"}

data: {"type":"end"}

Each line is a JSON event. Concatenate all token events to build the full response. See the API reference for all event types.

Step 6: Multi-turn sessions

For conversations where later questions depend on earlier context, use sessions:

Shell

# Create a session
SESSION_ID=$(curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api/sessions" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" \
  -X POST | jq -r '.session_id')

echo "Session: $SESSION_ID"

# First message
curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api/sessions/$SESSION_ID/chat" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I create a REST connection?"}' | jq '.response'

# Follow-up — the agent remembers the first message
curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api/sessions/$SESSION_ID/chat" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Now how do I schedule it to run daily?"}' | jq '.response'

# Review the full conversation
curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" | jq .

Session lifetime

Sessions are persisted for authenticated API key users. They're available across requests and survive server restarts. The agent maintains up to 20 messages of context history.

Billing & bring your own API key

Every Etlworks subscription includes up to $20/month of free agentic usage (exact amount depends on your subscription tier). Non-agentic tools like knowledge base search and template search are always free and unlimited.

If you need more than the free allowance, you have two options:

AI wallet — top up your balance in the Etlworks billing page. Usage beyond the free allowance is deducted from the wallet.
Bring your own OpenAI API key — bypass Etlworks billing entirely. All LLM calls go directly to OpenAI using your key, and agentic usage does not count toward Etlworks caps.

To set your own OpenAI key via the API:

Shell

# Set your own OpenAI API key
curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api-key" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"api_key": "sk-your-openai-api-key"}'

You can also set it via the Etlworks UI: open the AI Agent chat panel, click the settings icon, and enter your OpenAI API key.

When to use your own key

The free monthly allowance is sufficient for most interactive use. Consider bringing your own key for high-volume API integrations, CI/CD pipelines, or development/testing environments where you want unlimited usage without worrying about caps.

See the API reference → Billing & usage caps for full details on scoping, cost comparison, and key management endpoints.

Step 8: Use the client scripts

For convenience, we provide ready-made client scripts. Download them from the Downloads page.

Shell

# Install the requests library
pip install requests

# Set environment variables
export ETLWORKS_URL="https://your-instance.etlworks.com"
export ETLWORKS_API_KEY="your-api-key"

# Use as CLI
python etlworks_agent.py tools
python etlworks_agent.py chat "How do I create a connection?"
python etlworks_agent.py chat-stream "How do I schedule a flow?"

# Use as a library in your Python code
python -c "
from etlworks_agent import EtlworksAgent
agent = EtlworksAgent()
result = agent.chat('What CLI commands are available?')
print(result['response'])
"

Bash

# Make executable
chmod +x etlworks-agent.sh

# Set environment variables
export ETLWORKS_URL="https://your-instance.etlworks.com"
export ETLWORKS_API_KEY="your-api-key"

# Use
./etlworks-agent.sh tools
./etlworks-agent.sh chat "How do I create a connection?"
./etlworks-agent.sh chat-stream "How do I schedule a flow?"
./etlworks-agent.sh tool search_knowledge_base '{"query": "REST connection"}'

PowerShell

# Set environment variables
$env:ETLWORKS_URL = "https://your-instance.etlworks.com"
$env:ETLWORKS_API_KEY = "your-api-key"

# Use
.\etlworks-agent.ps1 tools
.\etlworks-agent.ps1 chat "How do I create a connection?"
.\etlworks-agent.ps1 chat-stream "How do I schedule a flow?"
.\etlworks-agent.ps1 tool search_knowledge_base '{"query": "REST connection"}'

# Multi-turn session
$session = .\etlworks-agent.ps1 session-create
.\etlworks-agent.ps1 session-chat $session "Create a REST connection"
.\etlworks-agent.ps1 session-chat $session "Now schedule it hourly"

Quickstart

Prerequisites

Step 1: Get your API key

Open user settings

Select the user

Generate the key

Step 2: Your first API call

Step 3: Explore the tools

Step 4: Chat with the agent

Step 5: Streaming responses

Step 6: Multi-turn sessions

Billing & bring your own API key

Step 8: Use the client scripts

Next steps

Full API reference

Code examples

Subagent integration