Quickstart

Get an API key, point at your instance, make your first request — and learn the conventions you'll see across all 400+ endpoints.

Prerequisites

• An Etlworks account (cloud, hybrid, or on-premise). Sign up free if you don't have one.
• A user with permission to generate API keys (admin, or a role with the API access capability).
• Either curl, Python 3.7+, or any HTTP client you prefer.

Step 1: Authentication

Two authentication modes are supported. Pick whichever fits your use case:

Option A — API key (recommended for service accounts)

1. Sign in to your Etlworks instance.
2. Open Settings → Users, select the user, click Edit.
3. Generate an API key under API Key. Optionally set an expiration.
4. Copy the key now — you won't see it again after closing the dialog.

Send the key on every request via the Authorization header:

Authorization: Bearer YOUR_API_KEY

Option B — Username/password → JWT

For interactive apps, exchange username + password for a short-lived JWT, then send the JWT on subsequent calls. Same Authorization: Bearer … header.

curl -s -X POST https://app.etlworks.com/rest/v1/token-auth \
  -H "Content-Type: application/json" \
  -d '{"login":"alice@example.com","password":"…"}'
# → { "token": "eyJhbGciOi…" }

JWTs expire (default: 24 hours). Refresh by re-authenticating, or call POST /v1/token-auth/refresh with a still-valid token.

Step 2: Base URL

https://your-instance.etlworks.com/rest

Replace your-instance.etlworks.com with your deployment hostname. Etlworks Cloud customers use app.etlworks.com. For on-premise installations use the host you configured.

All endpoints in this reference are relative to /rest. So /v1/flows in the docs means https://your-instance.etlworks.com/rest/v1/flows on the wire.

Step 3: Your first request

List your flows. This is the cheapest call you can make — pure read, returns fast, exercises auth.

curl -s https://app.etlworks.com/rest/v1/flows \
  -H "Authorization: Bearer YOUR_API_KEY"

You should see a JSON array of Flow objects (timestamps are unix milliseconds):

[
  {
    "id": 12345,
    "name": "Stripe to Snowflake — daily",
    "description": "Daily incremental sync of charges into the warehouse",
    "flowType": "ETL.database.event",
    "tags": ["production","stripe"],
    "enabledSchedules": 1,
    "disabledSchedules": 0,
    "latestFinishedStatus": "success",
    "createdBy": "alice@example.com",
    "created": 1715366462000,
    "modifiedBy": "alice@example.com",
    "modified": 1715369462000
  }
]

Step 4: Make a write call

Run a flow. Substitute a real flow ID from Step 3. The request body is a flat map of {string: string} parameters — not wrapped in {"params": …}. Send {} if your flow takes no parameters.

curl -s -X POST https://app.etlworks.com/rest/v1/flows/12345/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runDate":"2026-05-09"}'

The response is a FlowExecutionResponse with the auditId you'll use to poll progress:

{
  "flowId": 12345,
  "auditId": 8721934,
  "status": 0
}

The numeric status is the start outcome (0 = started, 1 = already running, 2 = canceled, etc.) — not the run's progress. To track progress, poll GET /v1/executions/{flowId}?auditId={auditId}; that returns a FlowAuditRecord with a string status field whose values follow the FlowStatus enum: queued, running, success, warning, error, canceled. Loop until you see one of the terminal four. The run-and-wait example on the examples page shows the full pattern.

Content types

The API speaks JSON throughout, with two exceptions: file uploads (multipart/form-data) and a handful of legacy export endpoints that return text/html for browser-rendered diagrams. Defaults:

• Request body: application/json on all POST/PUT calls (Content-Type required).
• Response body: application/json, except endpoints explicitly marked otherwise.
• Character encoding: UTF-8 throughout.

Pagination

Many list endpoints — particularly /v1/audit, /v1/executions/{flowId}/history, and bulk metric queries — accept offset/limit query parameters:

Where supported, total counts come back via the X-Total-Count response header.

Filtering & sort

Most list endpoints accept domain-specific filters as query params:

Specific filters per endpoint are documented in the API reference.

Error handling

Error response shape (4xx and 5xx):

{
  "status": 400,
  "error": "Bad Request",
  "message": "Field 'name' is required",
  "path": "/rest/v1/flows"
}

Rate limits

Cloud accounts share a soft limit of 600 requests/minute per organization. Hitting the limit returns 429 Too Many Requests with a Retry-After header (seconds). On-premise deployments are uncapped by default but configurable via system settings.

Heavy bulk operations (export/import, large list pulls) should use pagination and stagger requests rather than burst.