API reference

The public automation API: 126 endpoints in 21 groups. Every endpoint below is also in the OpenAPI spec, with full request and response schemas, and both are checked against the application source on every build.

Authentication

Every request carries a bearer token in the Authorization header: either an API key (long-lived, per user, optional expiry) or a JWT from POST /v1/token-auth/issue.

HTTP

Authorization: Bearer YOUR_TOKEN

JWTs last 8 hours by default; on-premise installations can change that with integrator.jwt.exp.period. Refresh a token that has not expired with POST /v1/token-auth/refresh. A few download and export endpoints also accept the token as an Authorization query parameter, so the URL can be opened directly.

A token carries the role of the user it belongs to. The API User role can call the Messages and CLI endpoints and HTTP listeners, but not flows, schedules or connections: generate the key for an Operator, Editor or Administrator for those. See the quickstart for setup.

Base URL

HTTP

https://app.etlworks.com/rest

That is Etlworks Cloud. On-premise, use your own hostname: https://your-host/rest. Every path in this reference is relative to /rest.

Errors

Errors use standard HTTP status codes. The body depends on the status:

400: the message as text/plain, or as JSON: {"error": "Field 'name' is required"}.
401 and 403: an empty body. 401 means the token is missing, invalid or expired; 403 means the role does not allow the call.
404: not found.
500: the message as text/plain, or an empty body for database errors.

Status code reference table: see quickstart errors.

Lists and pagination

List endpoints are not paginated: each returns everything in scope in one response. The exception is execution history, GET /v1/executions/{flowId}/history, which caps the result, reports how many records it left out in the X-Truncated-Count header, and takes lastAuditId to page back further. Timestamps are Unix epoch milliseconds.

Heads up: create/update payloads are metadata-driven

For connections, formats, flows, and listeners, the connectionType / formatType / flowType discriminator is not an arbitrary string and the properties bag is not an arbitrary object. Both are defined per-connector by JSON descriptors in the platform's connector library (src/main/resources/di/…): e.g. PostgreSQL is connection.db.postgres and its property keys are field.connection.template.host, field.connection.template.port, field.connection.template.database, etc.

Reliable way to discover the right shape for any connector: create one in the Etlworks UI, then GET /v1/connections/{id} (or /v1/formats/{id}, /v1/flows/{id}) and copy the resulting connectionType + properties verbatim into your script. Parameterize the values, leave the keys alone.

Authentication 5 endpoints

Tokens, refresh and tenant switching.

Method	Path	Description
`POST`	`/v1/token-auth/issue`	Exchange a login and password for a JWT. The token lasts 8 hours by default (`integrator.jwt.exp.period`, configurable on-premise).
`POST`	`/v1/token-auth/refresh`	Refresh a JWT that has not expired.
`POST`	`/v1/token-auth/revoke`	Revoke a JWT.
`GET`	`/v1/token-auth/tenants`	Tenants the caller can switch to.
`POST`	`/v1/token-auth/tenants/{tenantId}`	Switch tenant. Returns a new JWT scoped to the tenant.

API keys 4 endpoints

Long-lived keys for scripts and CI.

Method	Path	Description
`GET`	`/v1/users`	List users.
`GET`	`/v1/users/{userId}/get-api-key`	Get a user's current API key.
`POST`	`/v1/users/{userId}/new-api-key`	Generate or rotate a user's API key. Replaces any existing key for the user.
`POST`	`/v1/users/{userId}/revoke-api-key`	Revoke a user's API key.

Flows 17 endpoints

Create, edit, inspect, version, import and export flows.

Method	Path	Description
`GET`	`/v1/flows`	List flows. Returns every flow in scope in one response; there is no pagination.
`POST`	`/v1/flows`	Create a flow.
`POST`	`/v1/flows/bulk`	Bulk-edit flows. Rename, retag, delete or run many flows in one call.
`GET`	`/v1/flows/export`	Export flows as a bundle. Returns a text bundle to pass to an import endpoint.
`POST`	`/v1/flows/import`	Import flows. Preview first.
`POST`	`/v1/flows/import/preview`	Preview a flow import.
`POST`	`/v1/flows/inspect`	Run Flow Findings on a flow definition. Checks a flow against the built-in heuristics without saving it.
`GET`	`/v1/flows/recent`	Recently opened flows.
`GET`	`/v1/flows/{flowId}`	Get a flow.
`PUT`	`/v1/flows/{flowId}`	Update a flow. Replaces the whole flow.
`DELETE`	`/v1/flows/{flowId}`	Delete a flow. Moves it to the recycle bin.
`GET`	`/v1/flows/{flowId}/documentation`	Generated documentation for a flow.
`GET`	`/v1/flows/{flowId}/history`	Version history of a flow.
`GET`	`/v1/flows/{flowId}/history/{uuidFrom}/diff/{uuidTo}`	Diff two versions of a flow.
`GET`	`/v1/flows/{flowId}/history/{uuid}`	Get one saved version of a flow.
`PUT`	`/v1/flows/{flowId}/history/{uuid}/message`	Edit the save message of a flow version.
`GET`	`/v1/flows/{flowId}/usage`	Where a flow is referenced. Schedules, parent flows and listeners that reference it.

Runs 3 endpoints

Start and stop flow executions.

Method	Path	Description
`POST`	`/v1/flows/flow-name/{flowName}/run`	Run a flow by name. Every query parameter other than the ones listed is passed to the flow as a flow parameter.
`POST`	`/v1/flows/{flowId}/run`	Run a flow. The body is a flat map of flow parameters, or `{}`.
`POST`	`/v1/flows/{flowId}/stop`	Stop a running flow.

Executions 9 endpoints

Status, history, logs and dbt results of executions.

Method	Path	Description
`GET`	`/v1/executions/console/download`	Download an execution log. Accepts the token in the `Authorization` query parameter so the URL can be opened directly.
`GET`	`/v1/executions/{flowId}`	Get one execution. Look up by `auditId`, or by `messageId` for listener-triggered runs.
`GET`	`/v1/executions/{flowId}/audit/{auditId}/console`	The log of one execution.
`GET`	`/v1/executions/{flowId}/audit/{auditId}/console/live`	Tail the log of a running execution.
`GET`	`/v1/executions/{flowId}/audit/{auditId}/dbt`	dbt results of an execution. Model and test outcomes, timings, sources and freshness from a dbt flow run.
`GET`	`/v1/executions/{flowId}/audit/{auditId}/dbt/artifacts/{artifactName}`	Download a dbt artifact. Only the four artifact names listed are served; any other name returns 404.
`GET`	`/v1/executions/{flowId}/audit/{auditId}/running-tasks`	Transformations in flight.
`GET`	`/v1/executions/{flowId}/history`	Execution history of a flow. Returns up to 100 records per call.
`GET`	`/v1/executions/{flowId}/statuses`	Execution counts by status.

Schedules 13 endpoints

Timers, cron schedules and their history.

Method	Path	Description
`GET`	`/v1/schedules`	List schedules.
`POST`	`/v1/schedules`	Create a schedule.
`POST`	`/v1/schedules/bulk`	Bulk-edit schedules.
`GET`	`/v1/schedules/flows/{flowId}`	Schedules that run a flow.
`GET`	`/v1/schedules/{scheduleId}`	Get a schedule.
`PUT`	`/v1/schedules/{scheduleId}`	Update a schedule. Send the full schedule.
`DELETE`	`/v1/schedules/{scheduleId}`	Delete a schedule. Moves it to the recycle bin.
`POST`	`/v1/schedules/{scheduleId}/disable`	Disable a schedule. Pauses it without deleting it.
`POST`	`/v1/schedules/{scheduleId}/enable`	Enable a schedule.
`POST`	`/v1/schedules/{scheduleId}/flows/{flowId}/run`	Run a scheduled flow now. Runs the flow with the schedule's parameters and settings applied.
`GET`	`/v1/schedules/{scheduleId}/history`	Version history of a schedule.
`GET`	`/v1/schedules/{scheduleId}/history/{uuidFrom}/diff/{uuidTo}`	Diff two versions of a schedule.
`GET`	`/v1/schedules/{scheduleId}/history/{uuid}`	Get one saved version of a schedule.

Connections 15 endpoints

Database, storage, API and queue connections.

Method	Path	Description
`GET`	`/v1/connections`	List connections.
`POST`	`/v1/connections`	Create a connection.
`POST`	`/v1/connections/bulk`	Bulk-edit connections. Applies the listed actions to every id in the request, in order.
`GET`	`/v1/connections/recent`	Recently opened connections. Recently opened by the calling user.
`POST`	`/v1/connections/test`	Test a connection. Tests the connection in the body without saving it.
`GET`	`/v1/connections/{connectionId}`	Get a connection.
`PUT`	`/v1/connections/{connectionId}`	Update a connection. The body replaces the stored object; send the full object, not a patch.
`DELETE`	`/v1/connections/{connectionId}`	Delete a connection. Moves it to the recycle bin; restore it with `POST /v1/recycle-bin/{type}/{id}/restore`.
`POST`	`/v1/connections/{connectionId}/fields`	List the fields of an object.
`GET`	`/v1/connections/{connectionId}/history`	Version history of a connection.
`GET`	`/v1/connections/{connectionId}/history/{uuidFrom}/diff/{uuidTo}`	Diff two versions of a connection.
`GET`	`/v1/connections/{connectionId}/history/{uuid}`	Get one saved version of a connection.
`PUT`	`/v1/connections/{connectionId}/history/{uuid}/message`	Edit the save message of a connection version.
`POST`	`/v1/connections/{connectionId}/objects`	List tables, files or endpoints. Lists the objects reachable through a connection.
`GET`	`/v1/connections/{connectionId}/usage`	Where a connection is used.

Formats 12 endpoints

File and message formats.

Method	Path	Description
`GET`	`/v1/formats`	List formats.
`POST`	`/v1/formats`	Create a format.
`POST`	`/v1/formats/bulk`	Bulk-edit formats. Applies the listed actions to every id in the request, in order.
`GET`	`/v1/formats/recent`	Recently opened formats. Recently opened by the calling user.
`GET`	`/v1/formats/{formatId}`	Get a format.
`PUT`	`/v1/formats/{formatId}`	Update a format. The body replaces the stored object; send the full object, not a patch.
`DELETE`	`/v1/formats/{formatId}`	Delete a format. Moves it to the recycle bin; restore it with `POST /v1/recycle-bin/{type}/{id}/restore`.
`GET`	`/v1/formats/{formatId}/history`	Version history of a format.
`GET`	`/v1/formats/{formatId}/history/{uuidFrom}/diff/{uuidTo}`	Diff two versions of a format.
`GET`	`/v1/formats/{formatId}/history/{uuid}`	Get one saved version of a format.
`PUT`	`/v1/formats/{formatId}/history/{uuid}/message`	Edit the save message of a format version.
`GET`	`/v1/formats/{formatId}/usage`	Where a format is used.

Listeners 7 endpoints

HTTP, queue and other inbound listeners.

Method	Path	Description
`GET`	`/v1/listeners`	List listeners.
`POST`	`/v1/listeners`	Create a listener.
`POST`	`/v1/listeners/bulk`	Bulk-edit listeners. Applies the listed actions to every id in the request, in order.
`GET`	`/v1/listeners/recent`	Recently opened listeners. Recently opened by the calling user.
`GET`	`/v1/listeners/{listenerId}`	Get a listener.
`PUT`	`/v1/listeners/{listenerId}`	Update a listener. The body replaces the stored object; send the full object, not a patch.
`DELETE`	`/v1/listeners/{listenerId}`	Delete a listener. Moves it to the recycle bin; restore it with `POST /v1/recycle-bin/{type}/{id}/restore`.

Import and export 4 endpoints

Move connections and formats between tenants.

Method	Path	Description
`GET`	`/v1/io/export`	Export connections and formats as a bundle. Returns a text bundle.
`POST`	`/v1/io/import`	Import connections and formats.
`POST`	`/v1/io/import/preview`	Preview a connection and format import.
`GET`	`/v1/io/list`	Connections and formats available to export.

SQL 2 endpoints

Run SQL against a connection.

Method	Path	Description
`POST`	`/v1/explorer/sql/data`	Run SQL against a connection.
`GET`	`/v1/explorer/sql/data/executions/{executionId}/console`	The log of a SQL execution.

Connector metadata 4 endpoints

The parameter keys each connector, format and flow type accepts.

Method	Path	Description
`GET`	`/v1/di/metadata/connections/{key}`	Describe one connection type. Lists the parameter keys accepted in `properties`, with type, default and whether required.
`GET`	`/v1/di/metadata/flows/{key}`	Describe one flow type. Lists the parameter keys accepted in `properties`, with type, default and whether required.
`GET`	`/v1/di/metadata/formats/{key}`	Describe one format type. Lists the parameter keys accepted in `properties`, with type, default and whether required.
`GET`	`/v1/di/metadata/{type}`	List connector, format or flow types.

Macros 6 endpoints

Reusable parameterized snippets.

Method	Path	Description
`GET`	`/v1/macros`	List macros.
`POST`	`/v1/macros`	Create a macro.
`GET`	`/v1/macros/{macroId}`	Get a macro.
`PUT`	`/v1/macros/{macroId}`	Update a macro.
`DELETE`	`/v1/macros/{macroId}`	Delete a macro. Refused with 409 while a flow still uses it.
`GET`	`/v1/macros/{macroId}/usage`	Where a macro is used.

Functions 1 endpoint

Built-in transformation functions.

Method	Path	Description
`GET`	`/v1/functions`	List transformation functions.

Templates 3 endpoints

Flow templates.

Method	Path	Description
`GET`	`/v1/templates`	List flow templates.
`POST`	`/v1/templates/search`	Search flow templates.
`GET`	`/v1/templates/{templateId}`	Get a flow template.

Webhooks 8 endpoints

Outbound notifications on flow events.

Method	Path	Description
`GET`	`/v1/webhooks`	List webhooks.
`POST`	`/v1/webhooks`	Create a webhook. Deliveries carry `X-Etl-Webhook-Event`, `X-Etl-Webhook-Event-Id`, `X-Etl-Webhook-Id` and `X-Etl-Webhook-Entity-Id` headers, plus `X-Etl-Webhook-Signature` when a secret is set.
`GET`	`/v1/webhooks/metadata`	Webhook event types.
`GET`	`/v1/webhooks/{webhookId}`	Get a webhook.
`PUT`	`/v1/webhooks/{webhookId}`	Update a webhook.
`DELETE`	`/v1/webhooks/{webhookId}`	Delete a webhook.
`GET`	`/v1/webhooks/{webhookId}/events`	Recent deliveries.
`GET`	`/v1/webhooks/{webhookId}/events/{eventId}`	One delivery, with payload and response.

Messages 3 endpoints

Payloads received by listeners.

Method	Path	Description
`GET`	`/v1/messages`	List listener messages. Available to the API User role.
`POST`	`/v1/messages`	Search listener messages. Available to the API User role.
`GET`	`/v1/messages/{messageId}`	Get a message body. Available to the API User role.

CLI 2 endpoints

The built-in command line.

Method	Path	Description
`POST`	`/v1/cli`	Run CLI commands. Runs one or more built-in CLI commands and returns their output.
`GET`	`/v1/cli/commands`	List CLI commands.

Tags and search 3 endpoints

Tags and name search.

Method	Path	Description
`GET`	`/v1/search`	Search. Searches flows, connections, formats, schedules, webhooks, agents, macros and templates by name.
`POST`	`/v1/search`	Search with filters.
`GET`	`/v1/tags`	List tags in use.

Audit 3 endpoints

Audit trail of API calls.

Method	Path	Description
`GET`	`/v1/audit`	Recent API audit records.
`POST`	`/v1/audit`	Search API audit records.
`GET`	`/v1/audit/{auditId}`	Details of one audit record.

Recycle bin 2 endpoints

Deleted objects.

Method	Path	Description
`GET`	`/v1/recycle-bin`	List deleted objects.
`POST`	`/v1/recycle-bin/{type}/{id}/restore`	Restore a deleted object.

AI Agent API Separate subsite

The AI agent (Simba) has its own API surface, distinct from the platform CRUD endpoints. Documented separately:

Etlworks AI Agent API

Chat, streaming, tool calls, multi-turn sessions. Drive Simba from LangChain, CrewAI, AutoGen.

An endpoint you need is missing?

This reference covers the public automation API. The web application uses further endpoints that are not part of it and can change between releases. If you need to automate something the UI does and it is not here, email product@etlworks.com.