API reference

Complete reference for the Etlworks AI Agent Scripting API. All endpoints are under /rest/v1/ai-agent/api.

Authentication

All requests require an API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are generated in the Etlworks UI: Settings → Users → Edit user → API Key.

Base URL

https://your-instance.etlworks.com/rest/v1/ai-agent/api

Replace your-instance.etlworks.com with your Etlworks deployment URL. For on-premise installations, use your internal URL.

Error handling

Application-level errors in 200 responses use this format:

{
  "success": false,
  "error": "AI usage cap exceeded",
  "code": "cap_exceeded"
}

List tools

{
  "tools": [
    {
      "name": "search_knowledge_base",
      "description": "Search the knowledge base for articles, documentation, and support tickets related to the user's question.",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "The search query"
          }
        },
        "required": ["query"]
      },
      "agentic": false
    }
  ],
  "count": 7
}

Execute tool

{"query": "how to create a REST API connection"}

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

{
  "success": false,
  "error": "Tool not found: unknown_tool",
  "available_tools": ["search_knowledge_base", "host_cli", "host_list_commands", "..."]
}

Chat (complete response)

{
  "message": "How do I set up a daily sync from REST to PostgreSQL?",
  "include_tools": true,
  "system_prompt": "You are a helpful data integration assistant."
}

{
  "response": "To set up a daily sync from a REST API to PostgreSQL...",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tools_used": ["search_knowledge_base"],
  "usage": {
    "prompt_tokens": 1842,
    "completion_tokens": 456,
    "model": "gpt-4.1"
  }
}

Chat (streaming)

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":"To "}

data: {"type":"token","content":"set up "}

data: {"type":"token","content":"a daily sync..."}

data: {"type":"usage","prompt_tokens":1842,"completion_tokens":456,"model":"gpt-4.1"}

data: {"type":"end"}

Create session

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true
}

Session chat (complete response)

{
  "message": "Now how do I schedule it to run daily?",
  "include_tools": true
}

Session chat (streaming)

Get session messages

[
  {"role": "user", "content": "How do I create a REST connection?"},
  {"role": "assistant", "content": "To create a REST connection, follow these steps..."},
  {"role": "user", "content": "Now how do I schedule it?"},
  {"role": "assistant", "content": "To schedule the flow..."}
]

SSE event types

Streaming endpoints return Server-Sent Events. Each event is a JSON object on a data: line:

Tool reference

search_knowledge_base

Free Search KB articles, documentation, support tickets, and templates.

{"query": "how to create a REST API connection"}

search_templates

Free Search for flow and connection templates by topic or integration name.

{"query": "salesforce to database"}

create_support_ticket

Free Create a Zendesk support ticket.

{"subject": "Need help with REST connection", "description": "I am getting a 401 error when...", "user_email": "user@company.com"}

host_list_commands

Billed List all available CLI commands. Takes no arguments.

{}

host_cli

Billed Execute a CLI command on the Etlworks host.

{"command": "list connections"}

import_template

Billed Import a flow or connection template. Supports preview mode.

{"template_id": 42, "mode": "standard"}

Modes: standard (original flow type) or composer (visual canvas).

Billing & usage caps

Free monthly allowance

Every Etlworks subscription includes a free monthly agentic usage allowance of up to $20 (exact amount depends on your subscription tier). This covers both the web UI chat and API usage. Non-agentic tools (knowledge base search, template search, support tickets) are always free and unlimited.

API requests consume the same billing resources as the Etlworks chat UI:

• Free tools (agentic: false) — knowledge base searches, template searches, and support tickets do not count toward usage caps. Always free, no limits.
• Billed tools (agentic: true) — CLI commands and template imports count toward your monthly allowance.
• Chat endpoints — LLM token usage is tracked and counts toward your monthly allowance. If agentic tools are called during a chat, those are billed too.
• Cap exceeded — when the monthly allowance is used up, chat responses return "code": "cap_exceeded". Free tools continue to work. You can recharge via the AI Wallet or bring your own API key (see below).

Bring your own OpenAI API key

If you want to bypass Etlworks billing entirely, you can configure your own OpenAI API key. When a custom key is set, all LLM calls go directly to OpenAI using your key, and agentic usage does not count toward Etlworks monthly caps.

This is ideal for:

• High-volume API integrations that exceed the free monthly allowance
• Teams that prefer to manage their own OpenAI billing
• Development and testing without worrying about usage limits

Setting your API key

Via the Etlworks UI:

1. Log in to your Etlworks instance
2. Open the AI Agent chat panel
3. Click the settings icon in the chat header
4. Enter your OpenAI API key and save

Via the REST API:

# 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"}'

# Check if a key is configured
curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api-key" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY"

# Remove your custom key (reverts to Etlworks-managed billing)
curl -s "$ETLWORKS_URL/rest/v1/ai-agent/api-key/delete" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" \
  -X POST