HTTP API

The web interface has no privileged path into Syncle. Everything it does goes through the REST API documented on this page, so anything you can do in the interface you can also do from a script. Every route lives under /api, requests and responses are JSON, and a session cookie is the only authentication.

Conventions

The origin that serves the interface serves the API too: the web app proxies /api through to the API server, so with a default install the base URL is http://localhost:3002/api. The API container itself is not published outside the Docker network unless you expose it, so go through the web origin — the installation page covers the ports.

Every successful response is wrapped in a data envelope; every error is an error object with a machine-readable code, a human message, and a details field that is null unless the error carries extra data:

$ curl http://localhost:3002/api/health
{"data":{"ok":true,"checks":{"database":"ok","redis":"ok"}}}

$ curl http://localhost:3002/api/connections
{"error":{"code":"UNAUTHORIZED","message":"Authentication required","details":null}}

Scripts should branch on the code, not the HTTP status alone — two codes share status 400:

Authentication

The first account is created on first run with the setup token (the quickstart walks through that); it is an admin, and can make more, each with a role. Signing in sets db_session, a signed httpOnly cookie with SameSite=Lax, valid for the sessionTtlMinutes setting — one week by default. Keep it in a cookie jar and send it back on every call:

# sign in once, keeping the cookie
curl -c cookies.txt -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"your-password"}' \
  http://localhost:3002/api/auth/login

# every later call sends it back
curl -b cookies.txt http://localhost:3002/api/bridges

GET /api/version says which release is running — { version, source, node }, where source is build when the container image carried the version of the release tag it was built from, and package for a source checkout. It is behind the login on purpose: the public health probe says nothing beyond "up", and a version number is what someone scanning for a known flaw wants to read without asking. The same line is at the bottom of the Settings dialog.

Repeated failed logins lock the account out per IP and username and answer 429 with code RATE_LIMITED; setup attempts are limited per IP. Changing the password invalidates every outstanding session at once — the response re-issues the cookie for the session that made the change.

Workspaces

Workspaces are the top-level container for connections and bridges. A default workspace always exists, so you only meet these routes once you create a second one.

Connections

A connection is a saved database config. Passwords, SSH secrets and connection strings are encrypted at rest and redacted in every response. Routes that touch data accept a ?database= query parameter to address one database on the server; leave it off to use the connection's default.

Data operations

These are the routes behind the database workbench. What each engine supports varies — the driver's capability flags say which of them apply.

DDL, backup and restore

Backups come in two formats: json, a portable dump any engine can read back, and sql, a DDL-plus-INSERT script for relational engines only — MongoDB and Redis support just json.

Drivers and settings

GET /api/drivers lists the five supported engines with their labels, default ports, capability flags and the fields their connection forms need — the interface builds its connection dialog from this list, and a script can do the same.

GET /api/settings returns the resolved app settings (stored overrides merged over defaults); PUT /api/settings applies a partial update. The configuration page documents each setting and its default.

GET /api/settings/encryption reports on a change of master key: { previousKeys, reencrypted, unreadable, checkedAt } — how many previous keys are still accepted, and what the last pass over the stored secrets moved to the current key or could not read with any. POST /api/settings/encryption/rotate runs that pass now (it also runs at every start); signed in only, not with an API key.

GET /api/settings/instances lists the API processes that are alive on this database — [{ id, startedAt, version, leader, self }] — which one leads, and which one answered. One entry is the usual answer.

Accounts

An admin's, signed in (never with an API key). GET /api/auth/users lists them — { id, username, role, disabledAt, lastLoginAt, createdAt, updatedAt }; POST /api/auth/users with { username, password, role } makes one (role admin, operator or viewer; default operator); PUT /api/auth/users/:id with any of { role, newPassword, disabled } changes one (a new password or a disable ends its sessions); DELETE /api/auth/users/:id removes one; POST /api/auth/users/:id/sessions/end signs it out everywhere. A 400 says why something is refused: the last admin that can sign in, or your own account. GET /api/auth/me now carries role, and a request an account's role does not allow is a 403 that names the role it takes. POST /api/auth/reset/request takes an optional { username }: whose code to print; unnamed, the first admin's.

The activity log

GET /api/audit — an admin's — answers { entries: [{ id, at, actor: { type, id, name }, action, target: { type, id, name } | null, details, ip }], next }, newest first. limit (1–200, default 50); before = the next of the page before, for the page after it; action (one of the names below), actor (an actor's name, exactly), targetId, targetType narrow it. What is recorded and why is in the self-hosting guide. Actions: auth.setup, auth.login, auth.login_failed, auth.logout, auth.password_changed, auth.reset_requested, auth.password_reset, user.*, api_key.*, settings.update, encryption.rotate, workspace.*, connection.* (create, update, delete, query, rows_*, ddl, restore), bridge.* (create, update, delete, import, bulk_create, clone, run, cancel, retry, skip, start, stop, dead_letters_*, verify, verify_cancel, schema_accepted, slot_surrendered, cleanups_retry, cleanup_dismissed), retention.run, alert_channel.*.

API keys

A script or a CI job should not be given the operator's password. Create a key in Settings › Security and send it as a bearer token:

$ curl -H "Authorization: Bearer syn_…" http://localhost:3002/api/bridges

• The key is shown once, when it is created. What is stored is its SHA-256 — the key is 32 random bytes, so there is nothing to brute-force, and a copy of the metadata store yields no usable key. Lost keys are revoked and replaced, not recovered.
• Scope. read may GET and nothing else — not even a POST that only reads, so that what a read key can do is answerable by looking at the verb. full may do what the operator can, except anything about credentials: no key of any scope can list, create or revoke keys, change the password, or end sessions (403). A leaked key cannot mint more keys or lock you out.
• A key can be given an expiry; a revoked or expired key answers 401 at once. Revoked keys stay in the list, crossed out, with when they were last used — so "which key was that?" has an answer.

Health, metrics and alerts

Bridges

A bridge is the saved sync path, a job is one execution of it, and a delivery is one row or batch within a job — how bridges work covers the model. The routes below manage all three.

The body of a create or an update is the bridge's whole configuration. Its source can carry filters (ANDed; operators eq, neq, gt, gte, lt, lte, contains, startsWith, endsWith, in, isNull, notNull), and its transform.columns is the ordered list of column transforms — at most 100, each one of the five kinds below. A kind the server does not know is refused with a 400, never ignored.

A CDC trigger is { "kind": "cdc", "operations": [...], "startFrom": "now" | "beginning" }. beginning copies the table, then follows its changes with nothing lost in between; now (the default, and what every bridge saved before this option existed is) follows changes only.

{
  "source": {
    "kind": "table", "connectionId": "…", "table": "customers",
    "filters": [
      { "column": "age", "operator": "gte", "value": 18 },
      { "column": "deleted_at", "operator": "isNull" }
    ]
  },
  "transform": {
    "columns": [
      { "kind": "text", "column": "email", "op": "lower" },
      { "kind": "mask", "column": "email", "mode": "hash", "salt": "…" },
      { "kind": "mask", "column": "card", "mode": "partial", "keepStart": 0, "keepEnd": 4, "fill": "*" },
      { "kind": "cast", "column": "joined", "to": "date", "onError": "null" },
      { "kind": "default", "column": "tier", "value": "standard" },
      { "kind": "set", "column": "full_name", "template": "{{first}} {{last}}" }
    ]
  }
}

mask.mode is partial, redact, hash or null; cast.to is string, number, integer, boolean, date or json, and its onError is fail (the default), null or keep; text.op is trim, lower or upper. A column that a set or a default adds has to be named in transform.fields (when that list is pinned) and in a database target's mapping to be delivered, like any other column.

Jobs and deliveries

The numeric delivery-list parameters must be non-negative integers — anything else is a 400, not an empty result. Skipping only affects deliveries that are still queued.

Dead letters

Rows a watch or CDC bridge could not deliver under onError: continue, kept in full. How bridges work explains when a row lands here and what a retry does.

Each item carries op (insert, update, delete, or null for a watch bridge), the source rows as read, error, attempts, the sequence of the delivery it came from, and needsForce. In rows, binary values are shown as a byte count rather than dumped; the stored copy is complete. An entry with needsForce: true was left alone by a plain retry because its source row is gone and the bridge does not propagate deletes — send force: true to write the recorded row anyway, or discard it.

Live listening

Events

GET /api/events is a stream of server-sent events: one message per thing that changed, as it changes. The web app listens to it instead of asking every few seconds whether a run has moved on, and anything else with a session or an API key may listen the same way (curl -N -H "Authorization: Bearer …"). Each message's data is one JSON event:

{ "type": "bridge.job", "bridgeId": "…", "jobId": "…", "at": "2026-09-23T10:00:00.000Z" }

An event says only that something changed and what it was about — ask for the thing itself, the way you would have anyway. The kinds: bridge (bridgeId), bridge.job (bridgeId, jobId), bridge.deliveries (jobId), bridge.verification and bridge.deadLetters (bridgeId), connection and workspace (id), settings, users, apiKeys, audit, alertChannels. An id is present when the change was about one thing; a change to many at once names none. A burst of changes about one thing (the deliveries of a run, ten a second) is thinned to one event at once and one when the burst pauses. Events from every API process reach every stream, whichever process it was opened on.

The stream sends a comment every 25 seconds so that nothing between the two ends decides it is idle, and is ended by the server after 15 minutes; a browser's EventSource opens a new one by itself (it is told to wait 2 seconds), and any other client should do the same. Nothing is replayed on reconnection — ask again for what you care about, then listen. A proxy in front of Syncle has to pass the stream through unbuffered: the response says Cache-Control: no-transform and X-Accel-Buffering: no, which the usual ones honour.

Limits

• JSON request bodies cap at 50 MB — sized so backup and restore payloads, which carry whole dumps, fit.
• Ad-hoc query results cap at the maxQueryRows setting, default 5000 rows; the configuration page covers raising it globally or per connection.
• Browse pages return at most 1000 rows per request (default 100).
• A single skip call accepts at most 10,000 sequence numbers.