API reference

~400 endpoints organized into 14 groups. Each group section below lists the resources covered and the headline endpoints; full per-endpoint detail (request/response schemas) is rolling out in dedicated subpages — flagged with Coming until live.

Authentication

All requests require a Bearer token in the Authorization header — either an API key (long-lived, per-user) or a JWT (short-lived, minted via POST /v1/token-auth).

HTTP

Authorization: Bearer YOUR_TOKEN

API keys inherit the generating user's role and tenant scope. Generate from Settings → Users → Edit user → API Key. See the quickstart for setup.

Base URL

HTTP

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

Cloud customers use app.etlworks.com. On-premise: your configured hostname. Every path in this reference is relative to /rest.

Errors

Standard HTTP status codes. 4xx and 5xx errors return:

JSON

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

Status code reference table: see quickstart errors.

Pagination

List endpoints accept limit (default 50, max 200) and offset (default 0). Total counts via the X-Total-Count response header.

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.

Flows 28 endpoints

Build, edit, run, document, and inspect flows. The largest single resource — flows are the unit of work.

Resources covered: FlowsResource (/v1/flows) · LegacyFlowsResource (compat).

Method	Path	Description
`GET`	`/v1/flows`	List flows. Filters: `q`, `tag`, `type`, `since`.
`GET`	`/v1/flows/recent`	Recently-opened flows for the calling user.
`POST`	`/v1/flows`	Create a flow.
`GET`	`/v1/flows/{flowId}`	Get a flow by id.
`PUT`	`/v1/flows/{flowId}`	Edit a flow.
`DELETE`	`/v1/flows/{flowId}`	Delete (moves to recycle bin).
`POST`	`/v1/flows/{flowId}/run`	Run a flow now. Body is a flat `{string: string}` parameter map (or `{}`). Returns `FlowExecutionResponse` with `flowId`, `auditId`, `status`.
`GET`	`/v1/flows/{flowId}/usage`	Where is this flow referenced (schedules, parents, listeners).
`GET`	`/v1/flows/{flowId}/history`	Version history of edits.
`POST`	`/v1/flows/inspect`	Validate a flow definition without saving.
`GET`	`/v1/flows/{flowId}/documentation`	Plain-English description (for handoffs & audits).

Full flows reference → Coming

Executions 7 endpoints

Read the run-time side of flows: audit records, run logs, history, statuses. Each execution is identified by a (flowId, auditId) pair — the auditId comes back from POST /v1/flows/{flowId}/run. Status values follow the FlowStatus enum: queued, running, success, warning, error, canceled.

Resources covered: FlowExecutionsResource (/v1/executions) · LegacyDashboardResource.

Method	Path	Description
`GET`	`/v1/executions/{flowId}?auditId=…`	Get one audit record (`FlowAuditRecord`): status, timing, exception, metrics. Use `messageId` as an alternative lookup if you have it.
`GET`	`/v1/executions/{flowId}/history`	List recent audit records for this flow.
`GET`	`/v1/executions/{flowId}/statuses`	Counts by status (e.g. `{success: 1842, error: 33}`) for a time window.
`GET`	`/v1/executions/{flowId}/audit/{auditId}/console`	The full run-time log for one execution.
`GET`	`/v1/executions/{flowId}/audit/{auditId}/console/live`	Live tail of the run log while the flow is running.
`GET`	`/v1/executions/{flowId}/audit/{auditId}/running-tasks`	List in-flight transformations during a running execution.
`GET`	`/v1/executions/console/download`	Bulk-download multiple console logs.

Full executions reference → Coming

Schedules 15 endpoints

Cron-style schedules and HTTP listeners. Body matches the FlowSchedule model: flowId, name, schedule (the platform's scheduling syntax string), enabled, plus retry/email/timeout settings.

Resources covered: SchedulesResource (/v1/schedules) · HttpListenerResource.

Method	Path	Description
`GET`	`/v1/schedules`	List schedules.
`POST`	`/v1/schedules`	Create a schedule. Required: `flowId`, `name`, `schedule`.
`GET`	`/v1/schedules/{id}`	Get a single schedule.
`PUT`	`/v1/schedules/{id}`	Edit a schedule (full `FlowSchedule` body).
`PUT`	`/v1/schedules/{id}/disable`	Pause without deleting (sets `enabled=false`).
`PUT`	`/v1/schedules/{id}/enable`	Resume a paused schedule.
`DELETE`	`/v1/schedules/{id}`	Delete (moves to recycle bin).
`POST`	`/v1/schedules/{scheduleId}/flows/{flowId}/run`	Manually trigger a scheduled flow with the schedule's settings applied.
`POST`	`/v1/schedules/bulk`	Bulk enable/disable/delete by id list.
`GET`	`/v1/schedules/metadata`	Schedule-type catalog (used by the UI).
`GET`	`/v1/schedules/{id}/history`	Recent firings.

Full schedules reference → Coming

Composer 11 endpoints

Composer-specific endpoints: drafts, conversations, recent items. Used by the Composer UI; useful if you're building a custom flow editor.

Resources covered: ComposerResource (/v1/composer/flows).

Method	Path	Description
`GET`	`/v1/composer/flows/recent`	Recent Composer drafts for the calling user.
`POST`	`/v1/composer/flows`	Create a new Composer draft.
`POST`	`/v1/composer/flows/{id}/conversation`	Append a message to the in-flow agent conversation.
`POST`	`/v1/composer/flows/{id}/promote`	Promote a draft to a regular flow.

Full Composer reference → Coming

Connections 38 endpoints

Configure connectivity to databases, files, HTTP APIs, message queues, and SaaS apps. 270+ connector types. Includes file-format definitions, listeners, key uploads, and bulk export/import.

Resources covered: ConnectionsResource (13) · ConnectionsMetadataResource (5) · FormatsResource (10) · ListenersResource (6) · KeysUploadResource · IoExportImportResource (4).

Method	Path	Description
`GET`	`/v1/connections`	List connections. Filters: `q`, `tag`, `type`.
`POST`	`/v1/connections`	Create a connection.
`GET`	`/v1/connections/{id}`	Get connection by id (credentials redacted).
`PUT`	`/v1/connections/{id}`	Edit connection. Use `{{secret:…}}` placeholders for sensitive fields.
`POST`	`/v1/connections/{id}/test`	Test the connection (without committing changes).
`GET`	`/v1/connections/{id}/metadata`	Inspect schemas / tables / endpoints / columns.
`GET`	`/v1/formats`	List file-format definitions (CSV, JSON, XML, etc.).
`POST`	`/v1/listeners`	Register a queue/event listener (Kafka, SQS, …).
`POST`	`/v1/io/export`	Bundle flows + connections into a portable JSON payload.
`POST`	`/v1/io/import`	Import a bundle into a tenant. Always preview first.

Full connections reference → Coming

OAuth helpers ~30 endpoints across 11 providers

Built-in OAuth flows for major SaaS providers. Etlworks holds the OAuth client credentials so you don't have to register apps yourself for these providers.

Providers covered: Amazon Seller, Atlassian, Dropbox, Facebook, Google, HubSpot, Mailchimp, Microsoft, QuickBooks, Salesforce, Zoho.

Method	Path	Description
`GET`	`/v1/io/oauth/{provider}/url`	Get the consent URL to redirect the user to.
`POST`	`/v1/io/oauth/{provider}/callback`	Exchange the OAuth code for tokens; persist on a connection.
`POST`	`/v1/io/oauth/{provider}/refresh`	Refresh expired access tokens.
per-provider	e.g. `/v1/salesforce/…`	Provider-specific helpers (Salesforce login, Microsoft tenant resolution).

Full OAuth helpers reference → Coming

Explorer & SQL 13 endpoints

Inspect schemas, tables, views, endpoints in any connected system. Run ad-hoc SQL. Upload files directly to a connection.

Resources covered: ExplorerResource (10) · SqlResource (3) · UploadResource.

Method	Path	Description
`GET`	`/v1/explorer/connections/{id}/schemas`	List schemas in a database connection.
`GET`	`/v1/explorer/connections/{id}/tables`	List tables / views.
`GET`	`/v1/explorer/connections/{id}/sample`	Sample rows from a table.
`POST`	`/v1/explorer/sql`	Execute SQL against a connection. Returns rows + metadata.

Full Explorer reference → Coming

Templates & macros 21 endpoints

Search and deploy from the 3,979-template library. Manage parameter macros (reusable snippets). Browse the 200+ built-in transformation functions available in inline JS / Python / SQL.

Resources covered: TemplatesResource (10) · MacrosResource (10) · FunctionsResource (1).

Method	Path	Description
`GET`	`/v1/templates`	Search templates. Filters: `q`, `category`, `connector`.
`POST`	`/v1/templates/{id}/deploy`	Deploy a template into your tenant; returns the new flow id.
`GET`	`/v1/macros`	List macros (parameterized snippets).
`GET`	`/v1/functions`	List built-in transformation functions with signatures.

Full templates & macros reference → Coming

Authentication endpoints 21 endpoints

Resources covered: JwtAuthResource (5) · PasswordResetResource (3) · PasswordUpdateResource · SSOResource (2) · TOTPResource (6).

Method	Path	Description
`POST`	`/v1/token-auth`	Exchange username + password for a JWT.
`POST`	`/v1/token-auth/refresh`	Refresh an unexpired JWT.
`POST`	`/v1/passreset`	Initiate a password-reset email.
`POST`	`/v1/passupdate`	Change the calling user's password (current required).
`GET`	`/v1/sso/login`	Begin SAML/OIDC SSO redirect.
`POST`	`/v1/2fa/enroll`	Begin TOTP enrollment; returns secret + QR.
`POST`	`/v1/2fa/verify`	Verify a TOTP code (during sign-in or enrollment).

Full auth reference → Coming

Users & tenants 33 endpoints

Manage users (CRUD, roles, API keys). Multi-tenant accounts: list/switch tenants. Per-user profile, settings, notification preferences.

Resources covered: UsersResource (10) · TenantsResource (5) · UserProfileResource (18).

Method	Path	Description
`GET`	`/v1/users`	List users in the current tenant.
`POST`	`/v1/users`	Create a user. Body includes role, tenant, optional API key.
`POST`	`/v1/users/{id}/api-key`	Generate or rotate the user's API key.
`GET`	`/v1/tenants`	List tenants the calling user can see.
`POST`	`/v1/tenants/{id}/switch`	Switch active tenant for the current session.
`GET`	`/v1/userprofile`	Get the calling user's profile + settings.
`PUT`	`/v1/userprofile`	Update profile: name, email, locale, time zone.

Full users & tenants reference → Coming

Tags & search 9 endpoints

Tag any resource (flow, connection, schedule, …). Search across all tagged resources from one endpoint — faster than walking each list endpoint.

Resources covered: TagsResource (7) · SearchResource (2).

Method	Path	Description
`GET`	`/v1/tags`	List all tags in the tenant.
`GET`	`/v1/tags/{type}/{id}`	Get tags attached to a resource (flow, connection, …).
`PUT`	`/v1/tags/{type}/{id}`	Replace tags on a resource.
`GET`	`/v1/search`	Plain-English search across flows, connections, schedules, metadata.

Full tags & search reference → Coming

Audit & recycle bin 8 endpoints

Query the platform-wide audit log: every change, who made it, when. Recover deleted resources from the recycle bin (90-day retention by default).

Resources covered: AuditUiResource (5) · LegacyAuditResource · RecycleBinResource (3).

Method	Path	Description
`GET`	`/v1/audit`	Query audit events. Filters: `resourceType`, `resourceId`, `userId`, `action`, `since`.
`GET`	`/v1/audit/{id}`	Get one audit event with before/after diff.
`GET`	`/v1/recycle-bin`	List recently-deleted resources.
`POST`	`/v1/recycle-bin/{id}/restore`	Restore a deleted resource.
`DELETE`	`/v1/recycle-bin/{id}`	Purge permanently (irreversible).

Full audit reference → Coming

Webhooks & messages 11 endpoints

Webhooks are outbound: Etlworks POSTs to your URL when listed flow events fire (success / failure / etc.). Body matches the Webhook model: events[], url, method, headers[], secret (HMAC), flowIncludes[]/flowExcludes[]. For inbound triggers, use a listener connection (HTTP / Kafka / SQS / MQTT) instead.

Resources covered: WebhooksResource (8) · MessagesResource (3).

Method	Path	Description
`GET`	`/v1/webhooks`	List configured webhook subscriptions.
`POST`	`/v1/webhooks`	Subscribe to flow events.
`PUT`	`/v1/webhooks/{id}`	Edit a subscription.
`DELETE`	`/v1/webhooks/{id}`	Unsubscribe.
`GET`	`/v1/webhooks/{id}/events`	Recent outbound delivery attempts & their HTTP responses.
`GET`	`/v1/messages`	List in-app messages for the calling user.

Full webhooks reference → Coming

System & operations ~120 endpoints across 9 resources

Platform-level: settings, modules, system status, maintenance, metrics, billing, CLI, and the on-prem agents (CLI workers — not the AI agent; see AI Agent API).

Resources covered: SystemResource (8) · SettingsResource (3) · MaintenanceResource (8) · ModulesResource (2) · HealthResource · MetricsResource (25) · BillingResource (30) · CliResource (2) · AgentsResource (38, on-prem CLI workers).

Method	Path	Description
`GET`	`/v1/system/info`	Version, build, deployment mode (cloud / hybrid / on-prem).
`GET`	`/v1/system/health`	Liveness probe (no auth needed). Returns 200 when healthy.
`GET`	`/v1/settings`	Tenant-level settings (retention, branding, defaults).
`GET`	`/v1/modules`	Modules enabled in this deployment.
`GET`	`/v1/metrics/executions/summary`	Time-windowed execution stats (count, success rate, avg duration).
`GET`	`/v1/agents`	List on-prem CLI agents (workers) connected to this tenant.
`POST`	`/v1/agents/{id}/restart`	Restart an agent worker remotely.
`GET`	`/v1/billing/subscription`	Current subscription tier, seats, allowance usage.
`GET`	`/v1/billing/invoices`	Invoice history.
`POST`	`/v1/maintenance/backup`	On-demand tenant backup (admin only).

Full system & operations reference → Coming

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?

The reference will fill in over time as per-group pages roll out. If something blocks your work today, email product@etlworks.com — we'll either point you at it (it likely exists) or add it.