API-Referenz

Jeder Endpunkt der Verwaltungs-API der SQLly-Embedded-Bridge, generiert aus ihrem OpenAPI-Dokument (swagger.json), plus die sqlly.app-Verknüpfungsendpunkte.

swagger.json herunterladen OpenAPI 3.0 Version 1.0.0 Basis http://127.0.0.1:8445

Die SQLly-Bridge im Embedded-Modus stellt diese API auf ihrem Management-Listener bereit (--manage-bind, Standard 127.0.0.1:8445). Deine Webanwendung ruft es serverseitig auf, um Verbindungsprofile zu speichern, Verbindungen zu testen, Start-Token für angemeldete Benutzer auszustellen, Sitze zu überwachen und den Lizenzstatus zu lesen oder zu ändern.

Jedes /manage/... Aufruf erfordert Authorization: Bearer <manage token> (der Brücke --manage-token, mindestens 16 Zeichen). Die Inhalte sind JSON in beide Richtungen, höchstens 8 MB (abgelehnt mit 413 too_large sobald das Limit überschritten ist). Pfadsegmente und Werte der Abfragezeichenfolge werden prozentdekodiert; eine ungültige Escape-Sequenz ist 400 bad_request. Fehler haben immer die Form { "error": "<code>", "message": "<sentence>" }, plus problems , wenn ein Dokument mit Anmeldeinformationen ungültig ist. Die API sendet keine CORS-Header: Halte sie auf dem Loopback oder in einem privaten Netzwerk und setze sie niemals Browsern aus, da Profile Datenbankpasswörter enthalten.

das Linking Operationen befinden sich nicht auf der Bridge: Sie sind die öffentlichen Endpunkte von sqlly.app, die eine Admin-App verwendet, um eine Installation mit einer Lizenz zu verknüpfen, ohne einen Schlüssel zu kopieren. Ihr Server ist sqlly.app.

Leitfaden: sqlly.app/docs/embedded

Konventionen

  • Authentifizierung: Authorization: Bearer <manage token> bei jedem /manage/… aufrufen. Ein fehlendes oder falsches Token ist 401 unauthorized. /healthz und die sqlly.app-Verknüpfungspunkte benötigen keines.
  • Fehler sind { "error": "<code>", "message": "<sentence>" }. Verzweige nach error; anzeigen message. Ungültige Zugangsdaten-Dokumente liefern problems, eine Zeichenkette pro Fehler.
  • Bodies sind JSON, maximal 8 MB. Das Limit wird durchgesetzt, während der Body ankommt: die Bridge antwortet 413 too_large in dem Moment, in dem er übergeben wird, und puffert nie mehr. Ein Body, für dessen Ankunft mehr als 30 Sekunden vergehen, wird 408 timeout. Alles, was sich nicht parsen lässt, ist 400 bad_json, und eine unbekannte Route ist 404 not_found.
  • Pfadsegmente und Abfragewerte werden prozentdekodiert, also URL-codiere Benutzer-IDs und Zeitstempel (DELETE /manage/seats/a%2Fb gibt den Benutzer wieder frei a/b). Eine ungültige Escape-Sequenz oder ein Ergebnis, das nicht UTF-8 ist, ist 400 bad_request.
  • Feldnamen sind camelCase in den eigenen Payloads der API. Innerhalb eines Credential-Dokuments folgen sie dem Credential-Format (sql_auth_accounts, trust_server_certificate).

Endpunkte

Zustand

Liveness, kein Token nötig.

GET /healthz kein Token

Liveness-Probe

Antwortet, sobald der Management-Listener aktiv ist. Benötigt kein Token; verwenden Sie es in Startskripten und Service-Health-Checks.

200
Die Verwaltungs-API lauscht.
Beispielantwort 200
{
  "ok": true
}

Lizenz

Die Lizenz, unter der die Bridge läuft: Status, Check-in, Verknüpfen und Trennen.

GET /manage/status

Status der Brücke und der Lizenz

Alles, was eine Admin-Ansicht benötigt: der Lizenzstatus und woher er stammt, die Kontingente, die die signierte Berechtigung enthält, belegte Plätze, offene Sitzungen und die Proxy-URL, die Browser verwenden.

200
Aktueller Status.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
{
  "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
}
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
POST /manage/license/checkin

Checke jetzt bei sqlly.app ein

Verbundene und verlinkte Lizenzen: führt eine Check-in-Prüfung sofort durch, anstatt auf die 20-minütige Schleife zu warten. Offline-Lizenzen: liest die Lizenzdatei erneut ein und greift niemals auf das Netzwerk zu. In jedem Fall ist die Antwort der Status nach dem Versuch; ein Fehlschlag lässt den Zustand unverändert.

200
Status nach dem Check-in.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
409
not_linked: die Bridge ist nicht lizenziert, es gibt nichts zu melden.
422
license_file_invalid (offline): die Datei fehlt, ist beschädigt oder für einen anderen Schlüssel signiert.
502
store_unreachable oder grant_invalid: sqlly.app konnte nicht erreicht werden, oder ihre Antwort ließ sich nicht verifizieren.
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
Beispielantwort 409
{
  "error": "not_linked",
  "message": "this bridge is not linked to a license yet"
}
PUT /manage/license

Verknüpften Lizenzschlüssel installieren

Gibt eine Bridge, die ohne --license-key / --license-file seinen Schlüssel zur Laufzeit (normalerweise den Schlüssel, den deine Admin-App gerade über den Link-Flow von sqlly.app eingesammelt hat). Die Bridge meldet sich zuerst damit an und speichert ihn (<state-dir>/license-key, Modus 0600) nur, wenn sqlly.app mit einem verifizierten Grant antwortet; von da an läuft sie als verbundene Bridge, und der Schlüssel wird nach Neustarts wiederverwendet. Bei einem Fehler ändert sich nichts: Der verwendete Schlüssel dient weiter, bis der neue verifiziert ist. Das Ersetzen eines verknüpften Schlüssels durch einen einer anderen Lizenz gibt den Instanzplatz der alten Lizenz frei, sobald der neue Schlüssel verifiziert ist; ein neu erzeugter Schlüssel derselben Lizenz verwendet die Instanzzeile im Store wieder.

Anfragetext (LinkLicenseRequest)
{
  "licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}
200
Verknüpft. Der Status zeigt jetzt license.source: linked.
400
invalid_license_key: leerer, fehlerhafter, unbekannter oder widerrufener Schlüssel.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
409
license_from_flag: die Bridge wurde gestartet mit --license-key oder --license-file, daher wird ihre Lizenz nicht über diese API verwaltet.
502
store_unreachable: sqlly.app konnte nicht erreicht werden oder ihre Antwort ließ sich nicht verifizieren.
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/license

Diese Installation trennen

Gibt den Instanz-Slot dieser Bridge frei, widerruft den Schlüssel auf sqlly.app (nach bestem Bemühen), löscht den gespeicherten Schlüssel, schließt alle offenen Sitzungen und setzt die Bridge zurück auf unlicensed.

204
Getrennt.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
404
not_linked: kein verknüpfter Schlüssel gespeichert.
409
license_from_flag: die Bridge wurde gestartet mit --license-key oder --license-file, daher wird ihre Lizenz nicht über diese API verwaltet.
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Engines

Die Datenbank-Engines, die das Anmeldeinformationsformat akzeptiert, sodass deine UI die Liste nie fest codiert.

GET /manage/engines

Engines, die das Anmeldeinformationsformat akzeptiert

Jede Datenbank-Engine, die SQLly unterstützt, mit der engine ID zum Eintragen in ein Zugangsdaten-Dokument, ihr Standardport, ob server ein Dateipfad ist und die authentication.type Werte, die er akzeptiert.

200
Die Engines.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
[
  {
    "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"
    ]
  }
]
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Profile

Ein Profil ist ein benanntes SQLly-Anmeldeinformationsdokument: die Verbindungen (und Labels), die eine Benutzergruppe sieht. Die Bridge ist der maßgebliche Speicher; Geheimnisse erreichen nie den Browser.

GET /manage/profiles

Profile auflisten

Jedes gespeicherte Profil ohne seine Zugangsdaten.

200
Die Profile.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
[
  {
    "id": "analysts",
    "name": "Analysts",
    "connections": 2,
    "updatedAt": "2026-10-14T15:02:11Z"
  }
]
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
GET /manage/profiles/{id}

Ein Profil lesen

Das Profil mit seinem vollständigen Zugangsdaten-Dokument, Secrets eingeschlossen: Der Aufrufer ist deine vertrauenswürdige serverseitige App.

id
Pfad · Zeichenkette passend zu ^[A-Za-z0-9_-]{1,64}$ · erforderlich - deine ID für das Profil.
200
Das Profil.
400
invalid_profile_id: IDs sind 1-64 von A-Z a-z 0-9 _ -.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
404
unknown_profile: kein Profil hat diese ID.
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
Beispielantwort 404
{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}
PUT /manage/profiles/{id}

Ein Profil erstellen oder ersetzen

Speichert das Profil unter id (erstellen oder ersetzen). Das Dokument mit den Anmeldeinformationen wird vollständig validiert, bevor irgendetwas geschrieben wird: Jedes Problem, das der Parser findet, wird in problems, und ein ungültiges Dokument ändert nichts. Ein Dokument mit einer dateibasierten Engine (SQLite, DuckDB) wird genauso abgelehnt, es sei denn, die Bridge läuft mit --allow-file-engines true, weil eine solche Verbindung ihren Benutzern Dateizugriff auf dem Bridge-Host gibt. Bereits geöffnete Sitzungen behalten den Katalog, mit dem sie gestartet sind; Änderungen greifen erst beim nächsten Start.

id
Pfad · Zeichenkette passend zu ^[A-Za-z0-9_-]{1,64}$ · erforderlich - deine ID für das Profil.
Anfragetext (PutProfileRequest)
{
  "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
Gespeichert.
400
invalid_profile (mit problems: Parserprobleme oder jede dateibasierte Engine während --allow-file-engines aus ist), oder invalid_profile_id.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
500
storage: in das Zustandsverzeichnis konnte nicht geschrieben werden.
Beispielantwort 400
{
  "error": "invalid_profile",
  "message": "the credential document has 2 problems",
  "problems": [
    "connections[0].engine: unknown engine \"postgress\"",
    "connections[1].authentication.pasword: unknown key"
  ]
}
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/profiles/{id}

Ein Profil löschen

Entfernt das Profil. Offene Sitzungen behalten den Katalog, mit dem sie gestartet wurden; neue Start-Tokens dafür werden abgelehnt mit unknown_profile.

id
Pfad · Zeichenkette passend zu ^[A-Za-z0-9_-]{1,64}$ · erforderlich - deine ID für das Profil.
204
Gelöscht.
400
invalid_profile_id: IDs sind 1-64 von A-Z a-z 0-9 _ -.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
404
unknown_profile: kein Profil hat diese ID.
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
Beispielantwort 404
{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}

Starten

Launch-Tokens öffnen SQLly für einen Nutzer mit einem Profil. Plätze sind gleichzeitige Nutzer.

POST /manage/tokens

Ein Starttoken erstellen

Erstellt ein kurzlebiges Token, das SQLly öffnet für user mit profile, optional direkt in Abfragetabs (open, den Startkontext). Nimm das zurückgegebene proxyUrl und token auf die Seite, die SQLly lädt (globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN). Das Token lässt sich bis zum Ablauf (Seitenneuladen) wiederverwenden, und das Profil wird beim Ausstellen erfasst.

Ein Benutzer hält einen Platz, solange er eine offene Sitzung oder ein nicht abgelaufenes Token hat. Das Erstellen eines Tokens für einen Benutzer, der bereits einen Platz hält, schlägt in Bezug auf die Platzanzahl nie fehl; das Erstellen für einen neuen Benutzer schlägt fehl mit seat_limit wenn jeder Lizenzplatz belegt ist, wobei die Benutzer auf allen Bridges der Lizenz mitgezählt werden.

Anfragetext (MintTokenRequest)
{
  "user": "dana.analyst",
  "profile": "analysts",
  "open": {
    "connection": "Shop",
    "database": "sales",
    "title": "Big orders",
    "script": "SELECT *\nFROM orders\nWHERE total > @min_total",
    "parameters": {
      "min_total": 500
    },
    "cursor": {
      "line": 3,
      "column": 7
    }
  }
}
201
Das Token.
400
invalid_user (leer oder enthält Leerzeichen, höchstens 128 Zeichen), invalid_profile (das gespeicherte Profil ist nicht mehr gültig oder enthält eine dateibasierte Engine, während --allow-file-engines aus ist), oder invalid_open (der Startkontext eine unbekannte Verbindung, ein unbekanntes Feld oder einen unbekannten Typ, einen falschen Parameternamen oder -wert, einen Cursor außerhalb des zulässigen Bereichs nennt oder ein Limit übergibt; problems listet jeden Fehler mit seinem Pfad auf, z. B. open[1].cursor: …).
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
404
unknown_profile: kein Profil hat diese ID.
409
seat_limit: jeder Sitzplatz ist belegt. Gib einen frei (DELETE /manage/seats/{user}) oder einen größeren Tarif kaufen.
503
license_not_ok: die Lizenz ist nicht ok oder grace (veraltet, abgelaufen, widerrufen, nicht zugelassen, Domain-Abweichung oder nicht lizenziert). Die Nachricht gibt an, welche.
Beispielantwort 201
{
  "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,
  "openTabs": 0
}
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
GET /manage/seats

Genutzte Lizenzplätze

Benutzer, die einen Platz an dieser Bridge belegen, mit ihren offenen Sitzungen und aktiven Tokens. seatsUsed Zählt auch Benutzer, die sqlly.app auf anderen Brücken derselben Lizenz gemeldet hat.

200
Nutzung der Lizenzplätze.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
{
  "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"
    }
  ]
}
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/seats/{user}

Platz eines Benutzers freigeben

Entzieht die Token des Benutzers, schließt seine Sitzungen und gibt den Sitzplatz sofort frei. Ruf ihn auf, wenn sich ein Benutzer von deiner App abmeldet oder den Zugriff verliert. Das Freigeben eines Benutzers ohne Sitzplatz ist kein Fehler. Das Pfadsegment wird prozentdekodiert: a%2Fb gibt den Benutzer wieder frei a/b.

Benutzer
Pfad · Zeichenkette · erforderlich - Die Benutzer-ID, für die du Tokens ausgestellt hast (URL-codiert).
204
Freigegeben.
400
bad_request: das Segment ist keine gültige Prozentkodierung.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Verbindungen

Beweise, dass eine Verbindung funktioniert, bevor jemand sie benutzt.

POST /manage/test-connection

Eine Verbindung testen

Führt eine Wegwerf-Engine gegen ein Zugangsdaten-Dokument aus, das genau eine Verbindung enthält, und führt eine triviale Abfrage aus. Verbindungsfehler werden gemeldet als ok: false mit der eigenen Meldung der Engine (HTTP 200); nur ein unbrauchbares Dokument ist ein HTTP-Fehler.

Anfragetext (TestConnectionRequest)
{
  "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
Das Ergebnis, ob erfolgreich oder nicht.
400
invalid_profile: das Dokument ist ungültig, hält nicht genau eine Verbindung oder verwendet eine dateibasierte Engine, während --allow-file-engines ausgeschaltet ist (siehe problems).
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
{
  "ok": true,
  "elapsedMs": 212,
  "message": "Connected: SQL Server 17.0"
}
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Audit

Das Abfrage-Audit-Protokoll: jede Abfrage und jede Zeilenbearbeitung, die eine Sitzung ausgeführt hat, wer sie ausgeführt hat, über welche Verbindung und wie sie endete. Gespeichert im Arbeitsspeicher und in <state-dir>/queries.jsonl (inklusive SQL-Text) aufbewahrt, es sei denn, die Bridge läuft mit --query-log false.

GET /manage/queries

Abfrage-Auditprotokoll

Jede Abfrage und Zeilenbearbeitung, die die Sitzungen der Bridge ausgeführt haben, neueste zuerst: der Benutzer und das Profil des Start-Tokens, die benannte Verbindung (Name, Server, Engine, Datenbank), der SQL-Text (auf 64 KiB gekürzt, siehe sqlTruncated), wann es gestartet wurde, seinen Status und seine Dauer sowie den Fehler der Engine, wenn sie fehlschlug. Anfragen, die noch ausgeführt werden, werden mit Status aufgelistet running; eine Anfrage, die abgelehnt wurde, weil die Lizenz nicht in Ordnung war, ist failed mit der Lizenznachricht; alles, was ausgeführt wurde, als eine Sitzung geschlossen wurde, ist cancelled mit Fehler session closed.

Die Bridge behält die neuesten --query-log-max-entries Einträge (standardmäßig 20.000) im Speicher und in <state-dir>/queries.jsonl, sodass die Spur einen Neustart überlebt. Mit --query-log false wird nichts aufgezeichnet und die Antwort ist { "enabled": false, "queries": [] }.

Grenze
Abfrage · Ganzzahl - Zurückzugebende Einträge, auf 1-1000 beschränkt.
Benutzer
Abfrage · Zeichenkette - Nur diese Benutzer-ID (exakte Übereinstimmung, URL-codiert).
Profil
Abfrage · Zeichenkette - Nur diese Profil-ID (exakte Übereinstimmung).
seit
Abfrage · Zeichenkette (Datum-Uhrzeit) - Nur Einträge, deren at sich an oder nach diesem RFC 3339-Zeitstempel befindet (URL-codiert).
Status
Abfrage · QueryStatus - Nur Einträge in diesem Status.
200
Die passenden Einträge, neueste zuerst.
400
bad_request: limit ist keine ganze Zahl, since ist nicht RFC 3339, status ist unbekannt, oder ein Wert ist keine gültige Prozentkodierung.
401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
{
  "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'."
    }
  ]
}
Beispielantwort 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Verknüpfung

sqlly.app-Endpunkte (Server sqlly.app) zum Verknüpfen einer Installation mit einer Lizenz: du erstellst einen Code, der Besitzer genehmigt ihn in seinem Browser, du sammelst den eigenen Schlüssel der Installation einmalig und übergibst ihn dann mit PUT /manage/license an die Bridge.

GET /api/embedded/public-key sqlly.app kein Token

Öffentlicher Schlüssel für Lizenzsignatur (sqlly.app)

Der öffentliche PEM-Schlüssel, mit dem sqlly.app Lizenzerteilungen signiert, damit ein Betreiber ihn mit dem in die Bridge einkompilierten Schlüssel vergleichen kann.

200
PEM-Text.
503
signing_not_configured.

Schemas

Die obigen Objekte, wie definiert in swagger.json. Eine ? nach einem Typ bedeutet, dass er sein kann null.

Fehler

Jede Fehlermeldung. error ist ein stabiler Maschinencode; message ist ein Satz, den du einem Administrator zeigen kannst.

FeldTypBeschreibung
error * string
message * string
problems string[] Vorhanden für invalid_profile: jedes Problem, das der Credential-Parser gefunden hat.

LicenseState

ok und grace bedienen Abfragen; jeder andere Zustand lehnt die Arbeit mit einer Meldung ab, wie SQLly sie auch seinen Benutzern zeigt.

Eines von: ok grace stale not_admitted expired revoked domain_mismatch unlicensed

Statusbericht

FeldTypBeschreibung
version string Bridge-Version.
instanceId string Die ID dieses Bridge-Prozesses, wie sqlly.app sie sieht.
mode connected | offline
license LicenseReport
seatsUsed integer Genutzte Lizenzplätze in allen Bridges der Lizenz.
activeSessions integer Offene SQLly-Sitzungen auf dieser Bridge.
proxyUrl string Die WebSocket-URL, die Browser verwenden (--public-url).
allowLocalhostOrigins boolean
storeUrl string
allowFileEngines boolean Ob Profile dateibasierte Engines enthalten dürfen (--allow-file-engines).

LicenseReport

Kontingente stammen aus dem signierten Grant, niemals aus unsignierten Daten.

FeldTypBeschreibung
state LicenseState
source flag | file | linked | none flag: --license-key; file: --license-file; linked: gespeichert durch PUT /manage/license; none: nicht lizenziert.
licenseId string?
plan string? Plan-ID, oder custom für eine Lizenz mit eigenen Bedingungen.
planName string?
status string? Status von sqlly.app beim letzten Check-in: active, grace, expired, revoked, domain_mismatch.
seats integer Gleichzeitige Benutzer laut Lizenz.
sessionsPerSeat integer Offene SQLly-Tabs, die ein Benutzer halten darf.
instances integer Bridges, die gleichzeitig laufen dürfen (verbundene Lizenzen; 0 offline).
domain string? Die gebundene Domain; Browser müssen von dieser oder einer Subdomain stammen.
periodEnd string? Ende des bezahlten Zeitraums (ISO 8601).
graceEnd string? Festgelegt während der Kulanz: wann die Bridge den Dienst einstellt.
daysRemaining integer? Ganze Tage bis die Bridge den Dienst einstellt.
lastCheckinAt string (date-time)?
staleAt string (date-time)? Wann die Bridge als veraltet gilt: wenn kein Check-in erfolgreich war (letzte gültige Erteilung + 40 Minuten).
licenseFile string? Offline: die verwendete Lizenzdatei.
message string? Der Satz, den Nutzer sehen, wenn etwas nicht stimmt (auch Countdowns für die Gnadenfrist).
fromCache boolean Wahr, wenn die Bridge von ihrem zwischengespeicherten Grant gestartet wurde, weil sqlly.app nicht erreichbar war.
features string[]

LinkLicenseRequest

FeldTypBeschreibung
licenseKey * string Ein Schlüssel, der mit sqe_.

EngineInfo

FeldTypBeschreibung
id string das engine Wert für ein Dokument mit Anmeldeinformationen.
name string
defaultPort integer
fileBased boolean server ist ein Dateipfad und keine Anmeldung wird benötigt.
authentication string[] Akzeptiert authentication.type Werte.

ProfileSummary

FeldTypBeschreibung
id string
name string
connections integer Anzahl der Verbindungen im Dokument.
updatedAt string (date-time)

StoredProfile

FeldTypBeschreibung
id string
name string
credentials CredentialDocument
updatedAt string (date-time)

PutProfileRequest

FeldTypBeschreibung
name * string Anzeigename, der Benutzern in SQLly angezeigt wird.
credentials * CredentialDocument

CredentialDocument

Ein SQLly-Credentials-Dokument (im selben Format wie SQLlys Datei → Verbindungen importieren). Unbekannte Schlüssel sind Fehler, deshalb werden Tippfehler gemeldet statt ignoriert. Vollständige Referenz: sqlly.app/docs (Format der Anmeldeinformationsdatei).

FeldTypBeschreibung
format * sqlly-credentials
version * 1
clients Label[]
projects Label[]
environments Label[]
sql_auth_accounts SharedLogin[]
tunnel_profiles object[]
connections Connection[]

Bezeichnung

FeldTypBeschreibung
name * string
color string #RGB, #RRGGBB oder #RRGGBBAA.
image string Symbol als Daten-URI oder reines Base64 (PNG, JPEG, GIF, WebP, BMP, ICO, SVG; bis zu 1 MB).
safety object Nur die aufgelisteten Flags ändern sich.

SharedLogin

FeldTypBeschreibung
name * string
username * string
password string

Verbindung

FeldTypBeschreibung
name * string
engine * string Eine ID von GET /manage/engines.
server * string Host, IP, host\instance oder ein Dateipfad für SQLite/DuckDB.
port integer
database string
environment string local, dev, test, staging, production oder unset.
client string Ein Client-Label-Name.
project string Ein Projekt-Labelname.
authentication Authentication
tls object
timeout_seconds integer
statement_timeout_seconds integer
application_name string
safety object
favorite boolean
startup_sql string
tunnel_profile string
transport object Inline-Proxy, SSH- und Kube-Hops.
masking object { include: [...], exclude: [...] } Spalten-Masking-Regeln.

Authentifizierung

FeldTypBeschreibung
type * sql-login | integrated | entra-browser | entra-device-code | aws-rds-iam | gcp-cloud-sql-iam | auth-token | none
username string
password string
account string Name eines gemeinsamen Logins in sql_auth_accounts.
region string
profile string
token string

MintTokenRequest

FeldTypBeschreibung
user * string Deine stabile ID für den Benutzer (keine Leerzeichen). Lizenzplätze werden pro eindeutigem Benutzer gezählt.
profile * string Eine Profil-ID.
ttlSeconds integer Token-Lebensdauer; Standard ist --token-ttl-seconds (600) und ist auf 10 s - 24 h begrenzt.
open LaunchTab | LaunchTab[] Startkontext: ein Abfrage-Tab oder bis zu 8, die SQLly beim Sitzungsstart öffnet. Die erste Sitzung, die der Token durchlässt, bekommt sie; Neuladen und spätere Sitzungen nicht. Beim Ausstellen gegen das Profil geprüft (400 invalid_open). Nichts läuft, bis der Benutzer auf „Ausführen“ drückt. Anleitung: sqlly.app/docs/embedded/launch-context

LaunchTab

Ein Abfrage-Tab pro Start. Benötigt ein script, ein connection, oder beides.

FeldTypBeschreibung
connection string Eine Verbindung im Profil des Tokens, nach Name (Groß-/Kleinschreibung wird ignoriert, muss eindeutig sein) oder ID. Optional, wenn das Profil nur eine Verbindung hat; bei mehreren Verbindungen und ohne Namensangabe öffnet sich der Tab ohne Verbindung.
database string Datenbank, zu der gewechselt werden soll, anstelle der Standarddatenbank der Verbindung.
title string Der Tab-Titel.
script string Das SQL, das geladen werden soll, unverändert (maximal 256 KiB; CRLF wird zu LF zusammengeführt).
parameters object Werte im Skript für die @name Parameter, nach Name geschlüsselt (mit oder ohne @). Der Typ eines einfachen Wertes wird abgeleitet (ganze Zahl int, andere Zahl decimal, Boolean bool, Zeichenfolge text, null leer); verwende { type, value } um auszuwählen. Parameter, die das Skript nicht deklariert, erhalten eine -- sqlly param: Zeile; die Werte erscheinen in SQLlys Parameterleiste und werden nie von deiner App eingefügt.
cursor LaunchCursor

LaunchParameterValue

FeldTypBeschreibung
type text | int | decimal | bool | date | datetime | time | uuid | json | binary
value string | number | boolean

LaunchCursor

Caret-Position in script, 1-basiert; die Spalte zählt Zeichen und kann eine Stelle hinter dem Zeilenende liegen.

FeldTypBeschreibung
line integer
column integer

MintedToken

FeldTypBeschreibung
token string
expiresAt string (date-time)
proxyUrl string
user string
profile string
seatsUsed integer Genutzte Lizenzplätze einschließlich dieses Benutzers.
seats integer
openTabs integer Wie viele Tabs die Sitzung öffnet (0 ohne Startkontext).

SeatsReport

FeldTypBeschreibung
seats integer
seatsUsed integer
users UserSeat[]

UserSeat

FeldTypBeschreibung
user string
activeSessions integer
tokens integer Nicht abgelaufene Start-Token.
since string (date-time)

TestConnectionRequest

FeldTypBeschreibung
credentials * CredentialDocument

TestOutcome

FeldTypBeschreibung
ok boolean
elapsedMs integer
message string Die eigene Meldung der Engine, Erfolg oder Fehlschlag.

QueryStatus

running bis die Engine antwortet; dann completed, failed (siehe error) oder cancelled (vom Benutzer, oder session closed).

Eines von: running completed failed cancelled

QueryEntry

Eine geprüfte Anfrage.

FeldTypBeschreibung
id string Die Anfrage-ID der Engine, eindeutig innerhalb ihrer Sitzung.
sessionId integer Die Bridge-ID für die Browsersitzung.
kind query | row-edit
at string (date-time) Wann die Anfrage die Bridge erreichte.
user string Die Benutzer-ID des Start-Tokens.
profile string Die Profil-ID des Start-Tokens.
profileName string
connection string Der Name der Verbindung im Profil.
server string
database string? Die Datenbank des Profils, wenn es eine festlegt, sonst die in der Anfrage genannte Datenbank.
engine string Der Anzeigename der Engine.
sql string Der SQL-Text, oder row edit: <op> für eine Zeilenbearbeitung. Auf 64 KiB gekürzt.
sqlTruncated boolean
status QueryStatus
durationMs integer? Null während der Ausführung.
error string? Der Fehler der Engine für failed; session closed für eine Anfrage, die abgebrochen wurde, weil ihre Sitzung endete.

QueryListing

FeldTypBeschreibung
enabled boolean Falsch, wenn die Bridge mit --query-log false; dann queries immer leer.
queries QueryEntry[] Neueste zuerst.
total integer Einträge, die den Filtern entsprechen, vor limit angewendet wurde.
limit integer Die angewendete Seitengröße (1-1000).

CreateLinkRequest

FeldTypBeschreibung
name string Wird dem Eigentümer auf der Genehmigungsseite und auf seiner Embedded-Seite angezeigt.
hostname string
appVersion string

CreateLinkResponse

FeldTypBeschreibung
linkId string
code string Zeig das dem Eigentümer, damit er prüfen kann, ob es übereinstimmt.
secret string Serverseitig behalten; dort wird der Schlüssel erfasst.
linkUrl string Öffne das, damit der Besitzer es freigeben kann.
expiresAt string (date-time)
pollIntervalSeconds integer

LinkTokenRequest

FeldTypBeschreibung
linkId * string
secret * string

LinkPending

FeldTypBeschreibung
status pending
expiresAt string (date-time)

LinkApproved

FeldTypBeschreibung
status approved
licenseKey string Einmal genau zurückgegeben. An PUT /manage/license weitergeben.
keyId string
licenseId string
plan string Plan-ID, oder custom.
planName string
accountEmail string

* erforderlich