API reference

{ "email": "you@acme.com", "password": "correct horse", "name": "Ada" }

{
  "user":      { "id": "…", "email": "you@acme.com", "name": "Ada" },
  "workspace": { "id": "…", "name": "Ada's workspace", "role": "owner" }
}

Password must be ≥ 8 chars. The very first account ever becomes owner of the Default workspace; everyone else gets their own “<name>’s workspace”. A duplicate email is 409; a malformed one is 400.

{ "email": "you@acme.com", "password": "correct horse" }

{
  "user":      { "id": "…", "email": "you@acme.com", "name": "Ada" },
  "workspace": { "id": "…", "name": "Default", "role": "owner" }
}

Unknown email and wrong password both return the same 401 invalid email or password (no account enumeration). A user with no membership gets 403 account has no workspace. The first membership becomes the active workspace.

Deletes the server-side session and clears the cookie. Idempotent.

{ "ok": true }

{ "workspaceId": "…" }

{ "id": "…", "name": "Acme", "role": "editor" }

Not a member of the target → 403 you are not a member of that workspace.

{ "currentPassword": "…", "newPassword": "…" }

New password must be ≥ 8 chars and differ from the current one; a wrong currentPassword is a 400. Succeeds by keeping the current session and revoking every other session for the user.

{ "theme": "dark", "sidebar": "expanded" }

Stored verbatim. A non-object body, or one over 64 KB, is a 400.

{ "avatar": "data:image/png;base64,…" }

Accepts an https:// URL or a PNG/JPEG/WebP data URL, up to ~1 MB.

Refuses with 409 while the workspace still holds connections, pipelines, or datasets — empty it first. On success, 204.

Any member may leave; the sole remaining owner is blocked with 409. Returns 204.

{ "role": "editor" }

{ "userId": "…", "role": "editor" }

You can’t set a role at or above your own, or act on a member who outranks you (403); demoting the last owner is 409. Fires a member.role_changed notification.

Blocked (403) unless you outrank the target (or it’s yourself); removing the last owner is 409. Returns 204 and notifies the removed user.

Public peek so the accept page can render before login.

{ "valid": true, "workspaceName": "Acme", "role": "editor" }

Joins the workspace and switches your active session to it. Unknown token → 404; expired, revoked, or exhausted → 410 Gone. Re-accepting as an existing member is idempotent and consumes no use.

{ "workspaceId": "…", "workspaceName": "Acme", "role": "editor" }

{ "email": "bob@acme.com", "role": "viewer" }

{ "id": "…", "role": "viewer", "status": "pending", "inviteeEmail": "bob@acme.com" }

No account for that email, already a member, or already invited → 409. The invitee gets an invite.received notification (transactional).

{ "workspaceId": "…", "workspaceName": "Acme", "role": "viewer" }

Only the invitee may accept (else 404); a non-pending invitation is 409.

Returns 204 and notifies the inviter. Same ownership/state guards as accept.

Every registered connector spec — fields, and source/sink support flags.

Tests a not-yet-saved config. Secret refs are resolved first; nothing is persisted. role defaults to source (sink for write-only connectors).

{ "config": { "host": "…", "password": "${secret.PG_PW}" }, "role": "source" }

{ "ok": true }

Unknown connector → 400; a failed live probe → 502.

Bare array by default; ?archived=true for the archive; ?page=N (+ ?q, ?limit) → { items, total }.

[
  {
    "id": "…", "name": "Prod Postgres", "provider": "postgres",
    "config": { "host": "…" }, "placement": "cloud",
    "agentId": null, "createdAt": "2026-01-02T…Z"
  }
]

{
  "name": "Prod Postgres",
  "provider": "postgres",
  "config": { "host": "db", "password": "${secret.PG_PW}" },
  "placement": "cloud"
}

{ "id": "…", "name": "Prod Postgres", "provider": "postgres", "config": { … }, "placement": "cloud", "createdAt": "…" }

name and provider are required; an agent placement whose agentId isn’t an agent in this workspace is a 400.

Name, config, and placement are editable; the provider (connector kind) is immutable. Unknown id → 404.

Archives by default (soft delete, curation preserved); ?purge=true hard-deletes and cascades its datasets. A connection still referenced by live pipelines (archive) or any pipelines (purge) → 409. Success 204.

Brings an archived connection and its datasets back. 204.

Probes the stored config without moving data. Agent-placed → runs on the runtime synchronously.

{ "ok": true }

Lists the source’s streams and reconciles them into the dataset catalog atomically.

{ "summary": { "added": 3, "updated": 1, "removed": 0 }, "datasets": [ … ] }

{ "jobId": "…", "async": true }

Reads a bounded sample from one source stream. limit defaults to 50, capped at 200. Empty stream → first discovered stream.

{ "stream": "public.orders", "limit": 50 }

{
  "stream": "public.orders",
  "fields": [ { "name": "id", "type": "int64", "nullable": false } ],
  "rows":   [ [ 1, "…" ] ],
  "truncated": false
}

Filters: connectionId, folderId, tag, q. Offset paging via limit (default 100, max 500) + offset.

{
  "items": [
    {
      "id": "…", "connectionId": "…", "provider": "postgres",
      "physicalName": "public.orders", "displayName": "Orders",
      "type": "table", "schema": { … }, "rowEstimate": 12000,
      "status": "active", "folderId": null, "tags": [ "sales" ], "defined": false
    }
  ],
  "total": 42
}

Full datasetDTO. Unknown id → 404 dataset not found.

Raw stored schema JSON (or {}), written unwrapped.

Bounded row sample for the dataset’s underlying stream (previewDTO shape). Agent-placed connection → runtime passthrough.

{ "limit": 50 }

Samples up to 500 rows and computes per-column stats.

{
  "sampledRows": 500, "truncated": true,
  "columns": [
    { "name": "amount", "type": "float64", "nullable": false,
      "nulls": 0, "nullPct": 0, "distinct": 480, "min": "1.5", "max": "990" }
  ]
}

Any subset. folderId is tri-state: omit = keep, null/"" = move to root, uuid = move into folder.

{ "displayName": "Orders", "folderId": null, "tags": [ "sales" ] }

Previews a defined dataset (e.g. a SQL query) against a source connection without saving it. A connector that doesn’t support defined datasets → 422.

{ "definition": { "query": "select * from orders where region = 'EU'" } }

{ "stream": "preview", "fields": [ … ], "rows": [ … ], "truncated": true }

Persists a defined dataset. name required; a duplicate name → 409; unsupported connector → 422.

{ "name": "EU Orders", "definition": { "query": "select …" } }

{ "id": "…", "physicalName": "EU Orders", "defined": true, "definition": { … }, … }

Stateless, deterministic source→target column alignment with confidence + reason. No data is read or written.

{
  "source": [ { "name": "cust_id", "type": "int64" } ],
  "target": [ { "name": "customer_id", "type": "int64" } ]
}

{ "suggestions": [ { "source": "cust_id", "target": "customer_id", "confidence": 0.92, "reason": "…" } ] }

Every operator spec with its resolved JSON Schema — the builder palette is data-driven from this.

The JSON Schema for one operator’s config, written unwrapped. Unknown type → 404.

?archived=true for the archive; ?page=N (+ ?q) for numbered paging; otherwise a bare array.

spec (the full Document) is required; name is optional (blank keeps the current one). Connections are immutable. Validation failure → 400.

{ "name": "Orders → Warehouse", "spec": { … } }

Archives; ?purge=true hard-deletes and cascades run history (events, quarantine, state). 204.

All runs for the pipeline (array of runDTO).

?dryRun=true validates and reads without writing. Returns 202 with the created run (re-read post-orchestration, so a bound-runtime-offline failure is already reflected).

{ "id": "…", "pipelineId": "…", "status": "pending", "phase": "extract", "dryRun": false, "createdAt": "…" }

Runs the live builder Document over a source sample and returns a per-node trace (rejected rows capped at 20/node). Falls back to the saved spec when spec is omitted.

{ "stream": "public.orders", "limit": 50, "spec": { … } }

{
  "stream": "public.orders",
  "source": { "stream": "public.orders", "fields": [ … ], "rows": [ … ], "truncated": false },
  "nodes":  [ { "type": "filter", "name": "…", "fields": [ … ], "rows": [ … ],
               "rejected": [ { "reasons": [ "amount is null" ], "row": [ … ] } ] } ]
}

The secret references the pipeline’s connections need, and whether each is currently satisfied.

[ { "name": "PG_PW", "satisfied": true }, { "name": "S3_KEY", "satisfied": false } ]

Returns the schedule, or JSON null when none is set.

{ "pipelineId": "…", "cron": "0 * * * *", "enabled": true, "dryRun": false, "nextRunAt": "…", "lastRunAt": "…" }

Upserts a 5-field cron schedule; an invalid expression is a 400. When enabled, the response carries the computed nextRunAt.

{ "cron": "0 * * * *", "enabled": true, "dryRun": false }

Every schedule across the workspace (array of scheduleDTO).

Validates a cron string and returns the next 3 fire times. Query: ?cron=0 * * * *.

{ "valid": true, "next": [ "2026-01-02T10:00:00Z", "2026-01-02T11:00:00Z", "2026-01-02T12:00:00Z" ] }

Filters (all optional): status, pipelineId, since (RFC3339), q (pipeline name). Default keyset paging (?limit&cursor → nextCursor), or numbered (?page&limit → total).

{ "items": [ { "id": "…", "status": "running", "phase": "load", "rowsRead": 900, … } ], "nextCursor": "…" }

executedOn is added only on the single-run read — it reports whether the extract ran in the cloud or on a named agent.

{
  "id": "…", "pipelineId": "…", "status": "succeeded", "phase": "load",
  "rowsRead": 12000, "rowsWritten": 11980, "rowsQuarantined": 20,
  "rowsTotal": 12000, "dryRun": false,
  "createdAt": "…", "startedAt": "…", "finishedAt": "…",
  "executedOn": { "kind": "agent", "name": "office-runtime" }
}

Cooperative cancel. Idempotent: an already-finished or unknown run returns cancelling:false rather than an error.

{ "ok": true, "cancelling": true }

Server-Sent Events tail of the run log until a terminal state (or ~10 min). Each frame is a runEventDTO.

data: {"id":41,"ts":"…","level":"info","stream":"","message":"Extracted 12000 rows","rowsRead":12000,"rowsWritten":0}

Up to 200 rejected rows with their reasons and the raw row JSON. Rows can then be approved, discarded, or re-checked.

[ { "id": 1, "stream": "public.orders", "reasons": [ "amount is null" ], "row": { … } } ]

Writes selected quarantined rows into the pipeline’s destination (upsert when the target has a primary key, else append), bypassing the rule that rejected them, and marks each approved. Select by explicit ids or all:true (every still-pending row for the run). edits maps a row id → a partial {column: newValue} patch applied before the write. An agent-bound destination returns 409 (edge approval ships with the runtime); a non-writable connector → 400.

{ "ids": [1, 2], "all": false, "edits": { "1": { "amount": 0 } } }

{ "approved": 2, "failed": 0, "errors": [] }

Marks selected rows discarded without writing them. Same { ids | all } selection.

{ "discarded": 2 }

Re-checks selected rows (with any edits applied) against the pipeline’s validation rules without writing — reports which now pass. Nothing is mutated.

{ "revalidated": [ { "id": 1, "passes": true, "reasons": [] } ] }

Lists staged blob artifacts for the run. No blob backend → 503; no staged data → 404.

{
  "streams": [
    {
      "stream": "public.orders", "rows": 12000, "bytes": 900000, "parts": 2,
      "cursorField": "updated_at",
      "partList": [ { "n": 1, "rows": 6000, "bytes": 450000, "minCursor": "…", "maxCursor": "…" } ]
    }
  ]
}

Streams one staged stream as decompressed JSONL (application/x-ndjson, attachment). Optional ?part=N (1-based) for a single part; an out-of-range part is 400, a missing manifest 404.

Deletes the run’s staged data. A still-active run → 409; no artifacts → 204 (idempotent).

Purges staged artifacts for every finished run in the workspace.

{ "deleted": 7 }

Name must match ^[A-Za-z_][A-Za-z0-9_]*$. No secret store configured → 412. Returns 204.

{ "value": "s3cr3t" }

Unknown name → 404.

The caller’s notifications (?limit, default 50, max 200).

[ { "id": "…", "type": "schedule.skipped", "title": "…", "body": "…", "payload": {}, "readAt": null, "createdAt": "…" } ]

Marks all as read. 204.

Idempotent per-notification mark; unknown/other-user id still returns 204.

SSE of the caller’s new notifications (: ping heartbeat every 20s).

Cross-entity search over datasets, pipelines, connections, and runs (5 hits per group). Query: ?q.

{ "datasets": [ { "id": "…", "label": "Orders", "sublabel": "table" } ], "pipelines": [ … ], "connections": [ … ], "runs": [ … ] }

Dashboard KPIs, deltas, outcomes, throughput, runs-per-day, and top pipelines. Window: ?range=24h|7d|30d|all (default 7d) or ?from&to.

{
  "range": "7d",
  "kpis": { "rowsMoved": 120000, "rowsRead": 121000, "quarantined": 40,
            "finished": 12, "successRate": 92, "quality": 99, "avgDurationSec": 8.3 },
  "outcomes": { "succeeded": 11, "failed": 1, "cancelled": 0 },
  "topPipelines": [ { "id": "…", "name": "Orders → Warehouse", "rows": 90000 } ]
}

Workspace-wide SSE activity stream of run changes (: connected, then data: frames; : ping every 20s).

Mints a one-time, 15-minute enrollment token. Only its hash is stored; the plaintext is returned once.

{
  "token": "…",
  "expiresAt": "…",
  "installCommand": "setu enroll <token>",
  "controlPlaneUrl": "https://setu.example.com"
}

Enqueues a test job on the runtime; poll the returned job id. An offline runtime → 409 runtime is not online.

{ "provider": "postgres", "config": { "host": "…", "password": "${secret.PG_PW}" }, "role": "source" }

{ "jobId": "…" }

Soft-revokes the agent — its key stops authenticating. 204.

Poll an agent job’s status/result (e.g. the async connection test). Workspace-scoped; unknown → 404.

{ "id": "…", "kind": "test", "status": "succeeded", "result": { "ok": true } }

Exchanges a one-time enrollment token for a permanent agent key (returned once; only its hash is stored). An invalid/expired/replayed token → 401, no token consumed.

{ "token": "…", "version": "0.1.0" }

{ "agentId": "…", "agentKey": "…", "baseUrl": "https://setu.example.com" }

Long-poll for the next job (lease = 60s). 200 with a leased job, or 204 when the wait window (capped at 30s) closes.

{ "id": "…", "kind": "extract", "runId": "…", "connectionId": "…", "payload": { … } }

Self-contained extract instructions for an extract job. Config carries ${secret.X} refs intact — never resolved cloud-side. Wrong kind → 404.

{
  "runId": "…", "blobPrefix": "ws/…/pl/…/run/…/",
  "provider": "postgres", "config": { … },
  "streams": [ "public.orders" ], "blob": { … }
}

Load instructions for a load job, including the write mode and the compiled spec.

{
  "runId": "…", "blobPrefix": "ws/…/pl/…/run/…/",
  "provider": "postgres", "config": { … },
  "mode": "append", "spec": { … }, "blob": { … }
}

Renews the lease while working. Always 204 (a renewal on a no-longer-leased job is a harmless no-op).

status must be succeeded or failed. Idempotent completion; returns 204.

{ "status": "succeeded", "result": { "blobPrefix": "ws/…/run/…/", "rows": 12000 } }

{ "status": "failed", "error": "connect: connection refused" }

Forces one scheduling pass — an external heartbeat that wakes a sleepy free-tier host so due schedules still fire. Bearer SETU_TICK_TOKEN (constant-time compared); when that env is unset the route 404s so it’s never left open. Returns 204.

Readiness — pings the DB pool (2s timeout). 200 {"status":"ready"} or 503 {"status":"unavailable"}.

Prometheus metrics.