API reference

Liveness probe

Answers as soon as the management listener is up. Needs no token; use it from start scripts and service health checks.

200

The management API is listening.

{
  "ok": true
}

Bridge and license status

Everything an admin screen needs: the license state and where it came from, the allowances the signed grant carries, seats in use, open sessions, and the proxy URL browsers use.

200

Current status.

401

unauthorized: the manage token is missing or wrong.

{
  "version": "1.1.0",
  "instanceId": "b5e1c0f2-7d3a-4c8e-9a61-0f2d4b7e9c13",
  "mode": "connected",
  "license": {
    "state": "ok",
    "source": "linked",
    "licenseId": "emb_Q2x0b3VkU3FsbHkxMjM0NTY3",
    "plan": "embedded-25",
    "planName": "SQLly Embedded 25",
    "status": "active",
    "seats": 25,
    "sessionsPerSeat": 4,
    "instances": 1,
    "domain": "portal.example.com",
    "periodEnd": "2027-10-14T00:00:00+00:00",
    "graceEnd": null,
    "daysRemaining": 365,
    "lastCheckinAt": "2026-10-14T15:00:02Z",
    "staleAt": "2026-10-14T15:40:02Z",
    "licenseFile": null,
    "message": null,
    "fromCache": false,
    "features": [
      "embedded",
      "unlimited-connections",
      "all-engines",
      "test-connection"
    ]
  },
  "seatsUsed": 3,
  "activeSessions": 4,
  "proxyUrl": "wss://portal.example.com/sqlly/proxy",
  "allowLocalhostOrigins": false,
  "storeUrl": "https://sqlly.app",
  "allowFileEngines": false
}

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Check in with sqlly.app now

Connected and linked licenses: runs a check-in immediately instead of waiting for the 20-minute loop. Offline licenses: re-reads the license file and never touches the network. Either way the reply is the status after the attempt; a failure leaves the state unchanged.

200

Status after the check-in.

401

unauthorized: the manage token is missing or wrong.

409

not_linked: the bridge is unlicensed, there is nothing to check in.

422

license_file_invalid (offline): the file is missing, damaged, or signed for another key.

502

store_unreachable or grant_invalid: sqlly.app could not be reached, or its reply did not verify.

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

{
  "error": "not_linked",
  "message": "this bridge is not linked to a license yet"
}

Install a linked license key

Gives a bridge that was started without --license-key / --license-file its key at runtime (normally the key your admin app just collected from sqlly.app through the link flow). The bridge checks in with it first and stores it (<state-dir>/license-key, mode 0600) only if sqlly.app answers with a verified grant; from then on it runs as a connected bridge, and the key is reused after restarts. Nothing changes on failure: the key in use keeps serving until the new one has verified. Replacing a linked key with one of another license releases the old license's instance slot after the new key verifies; a regenerated key of the same license reuses the store's instance row.

{
  "licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}

200

Linked. The status now shows license.source: linked.

400

invalid_license_key: empty, malformed, unknown or revoked key.

401

unauthorized: the manage token is missing or wrong.

409

license_from_flag: the bridge was started with --license-key or --license-file, so its license is not managed through this API.

502

store_unreachable: sqlly.app could not be reached or its reply did not verify.

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Unlink this install

Releases this bridge's instance slot, revokes its key on sqlly.app (best effort), deletes the stored key, closes every open session and returns the bridge to unlicensed.

204

Unlinked.

401

unauthorized: the manage token is missing or wrong.

404

not_linked: no linked key is stored.

409

license_from_flag: the bridge was started with --license-key or --license-file, so its license is not managed through this API.

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Engines the credential format accepts

Every database engine SQLly supports, with the engine id to write in a credential document, its default port, whether server is a file path, and the authentication.type values it accepts.

200

The engines.

401

unauthorized: the manage token is missing or wrong.

[
  {
    "id": "sql-server",
    "name": "Microsoft SQL Server",
    "defaultPort": 1433,
    "fileBased": false,
    "authentication": [
      "sql-login",
      "integrated",
      "entra-browser",
      "entra-device-code"
    ]
  },
  {
    "id": "postgres",
    "name": "PostgreSQL",
    "defaultPort": 5432,
    "fileBased": false,
    "authentication": [
      "sql-login"
    ]
  },
  {
    "id": "sqlite",
    "name": "SQLite",
    "defaultPort": 0,
    "fileBased": true,
    "authentication": [
      "none"
    ]
  }
]

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

List profiles

Every stored profile without its credentials.

200

The profiles.

401

unauthorized: the manage token is missing or wrong.

[
  {
    "id": "analysts",
    "name": "Analysts",
    "connections": 2,
    "updatedAt": "2026-10-14T15:02:11Z"
  }
]

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Read one profile

The profile with its full credential document, secrets included: the caller is your trusted server-side app.

id

path · string matching ^[A-Za-z0-9_-]{1,64}$ · required - Your id for the profile.

200

The profile.

400

invalid_profile_id: ids are 1-64 of A-Z a-z 0-9 _ -.

401

unauthorized: the manage token is missing or wrong.

404

unknown_profile: no profile has that id.

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}

Create or replace a profile

Stores the profile under id (create or replace). The credential document is validated in full before anything is written: every problem the parser finds comes back in problems, and an invalid document changes nothing. A document holding a file-based engine (SQLite, DuckDB) is refused the same way unless the bridge runs with --allow-file-engines true, because such a connection gives its users file access on the bridge host. Sessions already open keep the catalog they started with; edits apply to the next launch.

id

path · string matching ^[A-Za-z0-9_-]{1,64}$ · required - Your id for the profile.

{
  "name": "Analysts",
  "credentials": {
    "format": "sqlly-credentials",
    "version": 1,
    "clients": [
      {
        "name": "Northwind Traders",
        "color": "#1E88E5"
      }
    ],
    "environments": [
      {
        "name": "Production",
        "color": "#C62828",
        "safety": {
          "only_allow_select": true
        }
      }
    ],
    "sql_auth_accounts": [
      {
        "name": "Reader",
        "username": "reader",
        "password": "…"
      }
    ],
    "connections": [
      {
        "name": "Northwind",
        "engine": "sql-server",
        "server": "sql01.internal",
        "database": "Northwind",
        "environment": "production",
        "client": "Northwind Traders",
        "authentication": {
          "type": "sql-login",
          "account": "Reader"
        },
        "tls": {
          "encrypt": true,
          "trust_server_certificate": true
        }
      },
      {
        "name": "Warehouse",
        "engine": "postgres",
        "server": "dw.internal",
        "database": "dw",
        "environment": "production",
        "client": "Northwind Traders",
        "authentication": {
          "type": "sql-login",
          "account": "Reader"
        },
        "tls": {
          "mode": "verify-full"
        }
      }
    ]
  }
}

200

Stored.

400

invalid_profile (with problems: parser problems, or each file-based engine while --allow-file-engines is off), or invalid_profile_id.

401

unauthorized: the manage token is missing or wrong.

500

storage: the state directory could not be written.

{
  "error": "invalid_profile",
  "message": "the credential document has 2 problems",
  "problems": [
    "connections[0].engine: unknown engine \"postgress\"",
    "connections[1].authentication.pasword: unknown key"
  ]
}

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Delete a profile

Removes the profile. Open sessions keep the catalog they started with; new launch tokens for it are refused with unknown_profile.

id

path · string matching ^[A-Za-z0-9_-]{1,64}$ · required - Your id for the profile.

204

Deleted.

400

invalid_profile_id: ids are 1-64 of A-Z a-z 0-9 _ -.

401

unauthorized: the manage token is missing or wrong.

404

unknown_profile: no profile has that id.

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}

Mint a launch token

Creates a short-lived token that opens SQLly for user with profile. Put the returned proxyUrl and token into the page that loads SQLly (globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN). The token can be reused until it expires (page reloads), and the profile is captured at mint time.

A user holds a seat while they have an open session or an unexpired token. Minting for a user who already holds a seat never fails on the seat count; minting for a new user fails with seat_limit when every seat of the license is in use, counting users on every bridge of the license.

{
  "user": "dana.analyst",
  "profile": "analysts",
  "ttlSeconds": 600
}

201

The token.

400

invalid_user (empty or contains whitespace, at most 128 characters), or invalid_profile (the stored profile no longer validates, or holds a file-based engine while --allow-file-engines is off).

401

unauthorized: the manage token is missing or wrong.

404

unknown_profile: no profile has that id.

409

seat_limit: every seat is in use. Release one (DELETE /manage/seats/{user}) or buy a larger plan.

503

license_not_ok: the license is not ok or grace (stale, expired, revoked, not admitted, domain mismatch, or unlicensed). The message says which.

{
  "token": "elt_q3J0n8w2Zx5rVb1kTq9yLs4dHf7cMa6p",
  "expiresAt": "2026-10-14T15:12:11Z",
  "proxyUrl": "wss://portal.example.com/sqlly/proxy",
  "user": "dana.analyst",
  "profile": "analysts",
  "seatsUsed": 3,
  "seats": 25
}

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Seats in use

Users holding a seat on this bridge, with their open sessions and live tokens. seatsUsed also counts users sqlly.app reported on other bridges of the same license.

200

Seat usage.

401

unauthorized: the manage token is missing or wrong.

{
  "seats": 25,
  "seatsUsed": 2,
  "users": [
    {
      "user": "dana.analyst",
      "activeSessions": 1,
      "tokens": 1,
      "since": "2026-10-14T15:02:11Z"
    },
    {
      "user": "sam.support",
      "activeSessions": 2,
      "tokens": 1,
      "since": "2026-10-14T14:40:03Z"
    }
  ]
}

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Release a user's seat

Revokes the user's tokens and closes their sessions, freeing the seat at once. Call it when a user signs out of your app or loses access. Releasing a user who holds no seat is not an error. The path segment is percent-decoded: a%2Fb releases the user a/b.

user

path · string · required - The user id you minted tokens for (URL-encoded).

204

Released.

400

bad_request: the segment is not valid percent-encoding.

401

unauthorized: the manage token is missing or wrong.

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Test one connection

Runs a throw-away engine against a credential document holding exactly one connection and executes a trivial query. Connection failures are reported as ok: false with the engine's own message (HTTP 200); only an unusable document is an HTTP error.

{
  "credentials": {
    "format": "sqlly-credentials",
    "version": 1,
    "connections": [
      {
        "name": "Northwind",
        "engine": "sql-server",
        "server": "sql01.internal",
        "database": "Northwind",
        "authentication": {
          "type": "sql-login",
          "username": "reader",
          "password": "…"
        },
        "tls": {
          "encrypt": true,
          "trust_server_certificate": true
        }
      }
    ]
  }
}

200

The outcome, success or not.

400

invalid_profile: the document is invalid, does not hold exactly one connection, or holds a file-based engine while --allow-file-engines is off (see problems).

401

unauthorized: the manage token is missing or wrong.

{
  "ok": true,
  "elapsedMs": 212,
  "message": "Connected: SQL Server 17.0"
}

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Query audit trail

Every query and row edit the bridge's sessions ran, newest first: the user and profile of the launch token, the connection it named (name, server, engine, database), the SQL text (cut to 64 KiB, see sqlTruncated), when it started, its status and duration, and the engine's error when it failed. Requests still running are listed with status running; a request refused because the license was not in order is failed with the license message; whatever was running when a session closed is cancelled with error session closed.

The bridge keeps the newest --query-log-max-entries entries (20 000 by default) in memory and in <state-dir>/queries.jsonl, so the trail survives a restart. With --query-log false nothing is recorded and the reply is { "enabled": false, "queries": [] }.

limit

query · integer - Entries to return, clamped to 1-1000.

user

query · string - Only this user id (exact match, URL-encoded).

profile

query · string - Only this profile id (exact match).

since

query · string (date-time) - Only entries whose at is at or after this RFC 3339 timestamp (URL-encoded).

status

query · QueryStatus - Only entries in this status.

200

The matching entries, newest first.

400

bad_request: limit is not a whole number, since is not RFC 3339, status is unknown, or a value is not valid percent-encoding.

401

unauthorized: the manage token is missing or wrong.

{
  "enabled": true,
  "total": 2,
  "limit": 200,
  "queries": [
    {
      "id": "q-7",
      "sessionId": 12,
      "kind": "query",
      "at": "2026-10-14T15:04:09.120Z",
      "user": "dana.analyst",
      "profile": "analysts",
      "profileName": "Analysts",
      "connection": "Northwind",
      "server": "sql01.internal",
      "database": "Northwind",
      "engine": "Microsoft SQL Server",
      "sql": "SELECT TOP 100 * FROM Orders",
      "sqlTruncated": false,
      "status": "completed",
      "durationMs": 184,
      "error": null
    },
    {
      "id": "q-6",
      "sessionId": 12,
      "kind": "query",
      "at": "2026-10-14T15:03:51.004Z",
      "user": "dana.analyst",
      "profile": "analysts",
      "profileName": "Analysts",
      "connection": "Northwind",
      "server": "sql01.internal",
      "database": "Northwind",
      "engine": "Microsoft SQL Server",
      "sql": "SELECT * FROM Ordres",
      "sqlTruncated": false,
      "status": "failed",
      "durationMs": 31,
      "error": "Invalid object name 'Ordres'."
    }
  ]
}

{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Start linking an install (sqlly.app)

Anonymous. Creates a link request and returns a short code, a secret only your app knows, and the URL where the license owner approves it. Show the code and open linkUrl for the owner, then poll POST /api/embedded/links/token every pollIntervalSeconds until it is approved. Links expire after 15 minutes.

{
  "name": "SQLly Embedded on portal-01",
  "hostname": "portal-01",
  "appVersion": "1.4.0"
}

201

Link created.

429

Rate limited.

503

link_unavailable: no code could be allocated; try again.

{
  "linkId": "eml_Y2h9u0bQ1sXk4tWm8pZr3vLa",
  "code": "K7Q-4MX",
  "secret": "pW0r7…",
  "linkUrl": "https://sqlly.app/embedded/link?code=K7Q-4MX",
  "expiresAt": "2026-10-14T15:17:11Z",
  "pollIntervalSeconds": 3
}

Poll for the linked key (sqlly.app)

Anonymous; the link secret is the credential. While the owner has not decided, answers 202 pending. Once approved, mints this install's own license key and returns it exactly once (the link is consumed). Hand the key straight to the bridge with PUT /manage/license; do not store it yourself.

200

Approved: the key, once.

202

Still waiting for the owner.

401

wrong_secret.

404

unknown_link.

410

link_used, link_denied, link_expired or license_revoked: this link can never complete. Start a new one.

429

Rate limited.

License-signing public key (sqlly.app)

The PEM public key sqlly.app signs license grants with, so an operator can compare it with the key compiled into the bridge.

200

PEM text.

503

signing_not_configured.