HTTP API

The web interface has no privileged path into Syncle — everything it does goes through the REST API on this page, so anything you can click, you can 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}}

$ 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

Syncle has a single admin account, created on first run with the setup token (the quickstart walks through that). 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

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.

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.

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.

Live listening

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.