Articles in this section

AI Agent API

  • Updated
Follow

The Etlworks AI Agent API lets your applications and AI agents drive Etlworks programmatically — search the knowledge base, execute CLI commands, import templates, and have full conversations with Simba (the Etlworks AI agent) over a simple REST API.

Full reference and downloads on the marketing site: etlworks.com/dev/ai/ — quickstart, API reference, examples, and client scripts (cURL, Python, Bash, PowerShell).

What you can do

Capability What it gives you
Direct tool access Call individual agent tools — search knowledge base, run CLI commands, search and import templates — without going through the LLM.
Full agent chat Send messages and get intelligent responses. The agent automatically selects and chains tools to answer complex questions.
Real-time streaming Stream responses token by token via Server-Sent Events. See tool calls in progress and get usage metrics live.
Multi-turn sessions Persistent sessions that remember context across messages — for complex workflows that need state.
Subagent integration Use Etlworks as a subagent in LangChain, CrewAI, AutoGen, or any orchestration framework. Delegate data integration tasks to a specialist.
API key auth Bearer token in the Authorization header. No OAuth flows, no token refresh.

Quick example

One-shot chat — ask the agent anything:

curl -s https://app.etlworks.com/rest/v1/ai-agent/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I create a REST API connection to load JSON data?"}'

Execute a tool directly without the LLM:

curl -s https://app.etlworks.com/rest/v1/ai-agent/api/tools/search_knowledge_base/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "schedule a flow to run every hour"}'

Python client — one-shot chat, direct tool execution, and multi-turn sessions:

from etlworks_agent import EtlworksAgent

agent = EtlworksAgent("https://app.etlworks.com", api_key="YOUR_API_KEY")

# One-shot chat
result = agent.chat("How do I create a REST API connection?")
print(result["response"])

# Execute a tool directly
kb = agent.execute_tool("search_knowledge_base", {"query": "schedule a flow"})
print(kb["result"])

# Multi-turn session
session = agent.create_session()
r1 = agent.session_chat(session, "Create a connection to api.example.com")
r2 = agent.session_chat(session, "Now schedule it to run every hour")

Full reference

Quickstart, complete API reference, downloadable client scripts (cURL, Python, Bash, PowerShell), and worked examples: etlworks.com/dev/ai/.

Etlworks as an MCP server

Etlworks also exposes the same agent tools through an MCP (Model Context Protocol) server. External AI clients — Claude Desktop, Claude Code, Cursor, Windsurf, and any other MCP-aware tool — can connect to your Etlworks instance and drive it through natural-language interactions.

Endpoint

POST https://<your-instance>.etlworks.com/rest/v1/ai-agent/mcp

Transport is JSON-RPC 2.0 over HTTP. The endpoint is stateless: each request is one MCP call (initialize, tools/list, tools/call).

Authentication

Pass your Etlworks API key as a bearer token:

Authorization: Bearer <your-api-key>

API keys are managed under Account → Security → API keys. The MCP server inherits the same tenant scoping as the REST AI Agent API — all calls run as the principal that owns the key.

Tools exposed

The MCP server exposes the same agent tools that Simba uses internally. Highlights:

  • Knowledge base and templates — search_knowledge_base, search_templates, search_function_templates.
  • Metadata and resources — metadata_search_resources, metadata_search_resource_types, mapping_lookup_metadata, composer_search_block_types.
  • Build and mutate flows — standard_flow_create, standard_flow_create_from_template, composer_apply_flow_update, mapping_apply_operations, composer_save_run_flow, composer_manage_schedule.
  • Resources — metadata_create_resource, metadata_create_http_connection, import_template.
  • Host CLI — host_cli (gated; requires explicit enablement), host_list_commands.
  • Web and account — public_web_research, create_support_ticket, book_demo, start_free_trial.
  • etlworks_assistant — a synthetic tool that runs the full Simba agent loop with tool access. Useful when the client wants Etlworks to do the planning rather than orchestrate tools individually. Gated by configuration; consumes AI tokens against your account's allowance.

MCP resources and prompts are not exposed in this release — only tools.

Configure an MCP client

For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "etlworks": {
      "url": "https://<your-instance>.etlworks.com/rest/v1/ai-agent/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Other MCP clients (Claude Code, Cursor, Windsurf) follow the same pattern — the URL and the bearer token are the only two values that change.

MCP vs. the REST AI Agent API

The two endpoints share the same tool registry and authentication. The difference is the transport:

  • REST AI Agent API — HTTPS with a single request / response per call. Best for backend integrations and scripts.
  • MCP server — JSON-RPC over HTTPS, designed to be plugged into IDE / desktop AI clients. Best for human-in-the-loop assistant workflows.

Pick the one that fits your client. The REST API remains the primary integration path; MCP is a convenience transport for AI-agent clients.

Related articles