Referencia de la API

Todos los endpoints de la API de administración del puente de SQLly Embedded, generados a partir de su documento OpenAPI (swagger.json), además de los endpoints de vinculación de sqlly.app.

Descargar swagger.json OpenAPI 3.0 versión 1.0.0 base http://127.0.0.1:8445

El puente SQLly en modo integrado expone esta API en su listener de gestión (--manage-bind, predeterminado 127.0.0.1:8445). Tu aplicación web lo llama desde su lado del servidor para guardar perfiles de conexión, probar conexiones, emitir tokens de lanzamiento para los usuarios con sesión iniciada, vigilar los asientos y leer o cambiar el estado de la licencia.

Cada /manage/... llamada necesita Authorization: Bearer <manage token> (del puente --manage-token, al menos 16 caracteres). Los cuerpos van en JSON en ambos sentidos, con un máximo de 8 MB (se rechaza con 413 too_large en cuanto se pasa del límite). Los segmentos de la ruta y los valores de la cadena de consulta se decodifican con codificación porcentual; un escape no válido es 400 bad_request. Los errores siempre son { "error": "<code>", "message": "<sentence>" }, además de problems cuando un documento de credenciales no es válido. La API no envía encabezados CORS: mantenla en loopback o en una red privada y nunca la expongas a navegadores, porque los perfiles contienen contraseñas de bases de datos.

La Linking las operaciones no están en el puente: son los puntos finales públicos de sqlly.app que una app de administración usa para vincular una instalación a una licencia sin copiar una clave. Su servidor es sqlly.app.

Guía: sqlly.app/docs/embedded

Convenciones

  • Autenticación: Authorization: Bearer <manage token> en cada /manage/… llamada. Un token ausente o incorrecto es 401 unauthorized. /healthz y los endpoints de enlace de sqlly.app no necesitan ninguno.
  • Errores son { "error": "<code>", "message": "<sentence>" }. Ramifica en error; muestra message. Los documentos de credenciales no válidos añaden problems, una cadena por error.
  • Cuerpos son JSON, 8 MB como máximo. El límite se aplica a medida que llega el cuerpo: el puente responde 413 too_large el momento en que se pasa y nunca almacena más en búfer. Un cuerpo que tarda más de 30 segundos en llegar es 408 timeout. Cualquier cosa que no se pueda analizar es 400 bad_json, y una ruta desconocida es 404 not_found.
  • Segmentos de ruta y valores de consulta se decodifican con codificación porcentual, así que codifica en la URL los IDs de usuario y las marcas de tiempo (DELETE /manage/seats/a%2Fb libera al usuario a/b). Un escape no válido o un resultado que no sea UTF-8 es 400 bad_request.
  • Nombres de campos están en camelCase en los payloads de la propia API. Dentro de un documento de credenciales siguen el formato de credencial (sql_auth_accounts, trust_server_certificate).

Endpoints

Estado

Sonda de actividad, sin token.

GET /healthz sin token

Sonda de actividad

Responde tan pronto como el listener de administración esté activo. No necesita token; úsalo desde los scripts de inicio y las comprobaciones de estado del servicio.

200
La API de gestión está a la escucha.
Ejemplo de respuesta 200
{
  "ok": true
}

Licencia

La licencia con la que funciona el puente: estado, registro, vinculación y desvinculación.

GET /manage/status

Estado del puente y de la licencia

Todo lo que necesita una pantalla de administrador: el estado de la licencia y de dónde proviene, las asignaciones que lleva la concesión firmada, asientos en uso, sesiones abiertas y la URL del proxy que usan los navegadores.

200
Estado actual.
401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 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
}
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
POST /manage/license/checkin

Conecta con sqlly.app ahora

Licencias conectadas y vinculadas: hace el registro de inmediato en lugar de esperar el ciclo de 20 minutos. Licencias sin conexión: vuelve a leer el archivo de licencia y nunca toca la red. En cualquier caso, la respuesta es el estado tras el intento; si falla, el estado no cambia.

200
Estado después del registro.
401
unauthorized: falta el token de administración o es incorrecto.
409
not_linked: el puente no tiene licencia, no hay nada que reportar.
422
license_file_invalid (sin conexión): falta el archivo, está dañado o está firmado con otra clave.
502
store_unreachable o grant_invalid: no se pudo acceder a sqlly.app, o su respuesta no superó la verificación.
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
Ejemplo de respuesta 409
{
  "error": "not_linked",
  "message": "this bridge is not linked to a license yet"
}
PUT /manage/license

Instalar una clave de licencia vinculada

Proporciona un puente que se inició sin --license-key / --license-file su clave en tiempo de ejecución (normalmente la clave que tu app de administración acaba de recoger de sqlly.app mediante el flujo de enlace). El puente se registra primero con ella y la guarda (<state-dir>/license-key, modo 0600) solo si sqlly.app responde con una concesión verificada; desde ese momento funciona como puente conectado, y la clave se reutiliza tras los reinicios. Si algo falla, nada cambia: la clave en uso sigue sirviendo hasta que la nueva quede verificada. Si sustituyes una clave vinculada por otra de otra licencia, se libera el cupo de instancias de la licencia anterior cuando la nueva se verifica; una clave regenerada de la misma licencia reutiliza la fila de instancia del almacén.

Cuerpo de la solicitud (LinkLicenseRequest)
{
  "licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}
200
Vinculado. El estado ahora muestra license.source: linked.
400
invalid_license_key: clave vacía, mal formada, desconocida o revocada.
401
unauthorized: falta el token de administración o es incorrecto.
409
license_from_flag: el puente se inició con --license-key o --license-file, por lo que su licencia no se gestiona a través de esta API.
502
store_unreachable: no se pudo acceder a sqlly.app o su respuesta no superó la verificación.
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/license

Desvincular esta instalación

Libera la ranura de instancia de este puente, revoca su clave en sqlly.app (en la medida de lo posible), elimina la clave almacenada, cierra todas las sesiones abiertas y devuelve el puente a unlicensed.

204
Desvinculado.
401
unauthorized: falta el token de administración o es incorrecto.
404
not_linked: no hay ninguna clave vinculada almacenada.
409
license_from_flag: el puente se inició con --license-key o --license-file, por lo que su licencia no se gestiona a través de esta API.
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Motores

Los motores de base de datos que acepta el formato de credenciales, para que tu interfaz nunca tenga la lista fija en el código.

GET /manage/engines

Motores que acepta el formato de credenciales

Cada motor de base de datos que SQLly soporta, con el engine id para escribir en un documento de credenciales, su puerto predeterminado, si server es una ruta de archivo, y los authentication.type valores que acepta.

200
Los motores.
401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 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"
    ]
  }
]
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Perfiles

Un perfil es un documento de credenciales de SQLly con nombre: las conexiones (y etiquetas) que ve un grupo de usuarios. El puente es el almacén de referencia; los secretos nunca llegan al navegador.

GET /manage/profiles

Listar perfiles

Cada perfil almacenado sin sus credenciales.

200
Los perfiles.
401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 200
[
  {
    "id": "analysts",
    "name": "Analysts",
    "connections": 2,
    "updatedAt": "2026-10-14T15:02:11Z"
  }
]
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
GET /manage/profiles/{id}

Leer un perfil

El perfil con su documento de credenciales completo, secretos incluidos: el llamador es tu aplicación confiable del lado del servidor.

id
ruta · cadena que coincide con ^[A-Za-z0-9_-]{1,64}$ · obligatorio - Tu id para el perfil.
200
El perfil.
400
invalid_profile_id: los ids son de 1 a 64 de A-Z a-z 0-9 _ -.
401
unauthorized: falta el token de administración o es incorrecto.
404
unknown_profile: ningún perfil tiene ese id.
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
Ejemplo de respuesta 404
{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}
PUT /manage/profiles/{id}

Crear o reemplazar un perfil

Almacena el perfil bajo id (crear o reemplazar). El documento de credenciales se valida por completo antes de escribir nada: cada problema que detecta el analizador se devuelve en problems, y un documento no válido no cambia nada. Un documento que contenga un motor basado en archivos (SQLite, DuckDB) es rechazado de la misma manera a menos que el puente se ejecute con --allow-file-engines true, porque ese tipo de conexión da a sus usuarios acceso a archivos en el host puente. Las sesiones ya abiertas conservan el catálogo con el que empezaron; los cambios se aplican en el próximo inicio.

id
ruta · cadena que coincide con ^[A-Za-z0-9_-]{1,64}$ · obligatorio - Tu id para el perfil.
Cuerpo de la solicitud (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
Almacenado.
400
invalid_profile (con problems: problemas del analizador, o cada motor basado en archivos mientras --allow-file-engines está apagado), o invalid_profile_id.
401
unauthorized: falta el token de administración o es incorrecto.
500
storage: no se pudo escribir el directorio de estado.
Ejemplo de respuesta 400
{
  "error": "invalid_profile",
  "message": "the credential document has 2 problems",
  "problems": [
    "connections[0].engine: unknown engine \"postgress\"",
    "connections[1].authentication.pasword: unknown key"
  ]
}
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/profiles/{id}

Eliminar un perfil

Elimina el perfil. Las sesiones abiertas mantienen el catálogo con el que empezaron; los nuevos tokens de lanzamiento para él se rechazan con unknown_profile.

id
ruta · cadena que coincide con ^[A-Za-z0-9_-]{1,64}$ · obligatorio - Tu id para el perfil.
204
Eliminado.
400
invalid_profile_id: los ids son de 1 a 64 de A-Z a-z 0-9 _ -.
401
unauthorized: falta el token de administración o es incorrecto.
404
unknown_profile: ningún perfil tiene ese id.
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
Ejemplo de respuesta 404
{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}

Lanzar

Los tokens de lanzamiento abren SQLly para un usuario con un perfil. Los asientos son usuarios concurrentes.

POST /manage/tokens

Generar un token de lanzamiento

Crea un token de corta duración que abre SQLly para user con profile, opcionalmente directamente en las pestañas de consulta (open, el contexto de lanzamiento). Coloca el proxyUrl y token devuelto en la página que carga SQLly (globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN). El token puede reutilizarse hasta que expire (recarga de página), y el perfil se captura en el momento de la generación.

Un usuario ocupa un asiento mientras tenga una sesión abierta o un token sin caducar. Emitir un token para un usuario que ya ocupa un asiento nunca falla por el límite de asientos; emitir uno para un usuario nuevo falla con seat_limit cuando cada asiento de la licencia está en uso, contando usuarios en cada puente de la licencia.

Cuerpo de la solicitud (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
El token.
400
invalid_user (vacío o con espacios en blanco, 128 caracteres como máximo), invalid_profile (el perfil almacenado ya no se valida, o contiene un motor basado en archivos mientras --allow-file-engines está apagado), o invalid_open (el contexto de lanzamiento nombra una conexión desconocida, un campo o tipo desconocido, un nombre o valor de parámetro incorrecto, un cursor fuera de rango, o pasa un límite; problems lista cada error con su ruta, por ejemplo open[1].cursor: …).
401
unauthorized: falta el token de administración o es incorrecto.
404
unknown_profile: ningún perfil tiene ese id.
409
seat_limit: cada asiento está en uso. Libera uno (DELETE /manage/seats/{user}) o compra un plan más grande.
503
license_not_ok: la licencia no está ok o grace (obsoleto, caducado, revocado, no admitido, con dominio que no coincide o sin licencia). El mensaje indica cuál.
Ejemplo de respuesta 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
}
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
GET /manage/seats

Asientos en uso

Usuarios con asiento en este puente, con sus sesiones abiertas y sus tokens activos. seatsUsed también cuenta a los usuarios que sqlly.app notificó en otros puentes de la misma licencia.

200
Uso de asientos.
401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 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"
    }
  ]
}
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/seats/{user}

Liberar el asiento de un usuario

Revoca los tokens del usuario y cierra sus sesiones, liberando el asiento de inmediato. Llámalo cuando un usuario cierre sesión en tu aplicación o pierda el acceso. Liberar a un usuario sin asiento no es un error. El segmento de la ruta va decodificado (percent-decoded): a%2Fb libera al usuario a/b.

usuario
ruta · cadena · requerido - El ID de usuario para el que acuñaste tokens (codificado en URL).
204
Liberado.
400
bad_request: el segmento no es una codificación porcentual válida.
401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Conexiones

Comprueba que una conexión funciona antes de que alguien la use.

POST /manage/test-connection

Probar una conexión

Ejecuta un motor desechable contra un documento de credenciales que contiene exactamente una conexión y ejecuta una consulta trivial. Los fallos de conexión se informan como ok: false con el propio mensaje del motor (HTTP 200); solo un documento inutilizable es un error HTTP.

Cuerpo de la solicitud (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
El resultado, con éxito o no.
400
invalid_profile: el documento no es válido, no contiene exactamente una conexión o contiene un motor basado en archivos mientras --allow-file-engines está apagado (ver problems).
401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 200
{
  "ok": true,
  "elapsedMs": 212,
  "message": "Connected: SQL Server 17.0"
}
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Auditoría

El historial de auditoría de consultas: cada consulta y edición de filas que ejecutó una sesión, quién la ejecutó, en qué conexión y cómo terminó. Se conserva en memoria y en <state-dir>/queries.jsonl (Texto SQL incluido) a menos que el puente se ejecute con --query-log false.

GET /manage/queries

Registro de auditoría de consultas

Cada consulta y edición de fila que ejecutaron las sesiones del puente, más recientes primero: el usuario y perfil del token de lanzamiento, la conexión que nombró (nombre, servidor, motor, base de datos), el texto SQL (recortado a 64 KiB, ver sqlTruncated), cuándo comenzó, su estado y su duración, y el error del motor si falló. Las peticiones que siguen en ejecución se listan con el estado running; una solicitud rechazada porque la licencia no estaba en orden es failed con el mensaje de la licencia; lo que se estaba ejecutando cuando se cerró una sesión es cancelled con error session closed.

El puente conserva las últimas --query-log-max-entries entradas (20 000 por defecto) se guardan en memoria y en <state-dir>/queries.jsonl, así que el registro sobrevive a un reinicio. Con --query-log false no se registra nada y la respuesta es { "enabled": false, "queries": [] }.

límite
consulta · entero - Entradas a devolver, limitadas a 1-1000.
usuario
consulta · cadena - Solo este ID de usuario (coincidencia exacta, codificado en URL).
perfil
consulta · cadena - Solo este ID de perfil (coincidencia exacta).
desde
consulta · cadena (fecha y hora) - Solo entradas cuyo at sea de este timestamp RFC 3339 en adelante (codificado en URL).
estado
consulta · QueryStatus - Solo entradas en este estado.
200
Las entradas coincidentes, primero las más recientes.
400
bad_request: limit no es un número entero, since no es RFC 3339, status desconocido, o un valor no es una codificación porcentual válida.
401
unauthorized: falta el token de administración o es incorrecto.
Ejemplo de respuesta 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'."
    }
  ]
}
Ejemplo de respuesta 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Vinculación

endpoints de sqlly.app (servidor sqlly.app) para vincular una instalación a una licencia: crea un código, el propietario lo aprueba en su navegador, recoge una vez la clave de la propia instalación y se la pasa al puente con PUT /manage/license.

GET /api/embedded/public-key sqlly.app sin token

Clave pública para la firma de licencias (sqlly.app)

La clave pública PEM con la que sqlly.app firma las concesiones de licencia, para que un operador pueda compararla con la clave compilada en el puente.

200
Texto PEM.
503
signing_not_configured.

Esquemas

Los objetos anteriores, tal como están definidos en swagger.json. Una ? después de un tipo significa que puede ser null.

Error

Cada respuesta de error. error es un código de máquina estable; message es una frase que puedes mostrar a un administrador.

CampoTipoDescripción
error * string
message * string
problems string[] Presente para invalid_profile: cada problema que el analizador de credenciales encontró.

LicenseState

ok y grace sirve consultas; cualquier otro estado rechaza el trabajo con un mensaje que SQLly muestra a sus usuarios.

Uno de: ok grace stale not_admitted expired revoked domain_mismatch unlicensed

StatusReport

CampoTipoDescripción
version string Versión del puente.
instanceId string Id de este proceso de puente tal como lo ve sqlly.app.
mode connected | offline
license LicenseReport
seatsUsed integer Asientos en uso en cada puente de la licencia.
activeSessions integer Sesiones SQLly abiertas en este puente.
proxyUrl string La URL de WebSocket que usan los navegadores (--public-url).
allowLocalhostOrigins boolean
storeUrl string
allowFileEngines boolean Si los perfiles pueden contener motores basados en archivos (--allow-file-engines).

LicenseReport

Los permisos provienen de la concesión firmada, nunca de datos sin firmar.

CampoTipoDescripción
state LicenseState
source flag | file | linked | none flag: --license-key; file: --license-file; linked: almacenado por PUT /manage/license; none: sin licencia.
licenseId string?
plan string? Id del plan, o custom para una licencia emitida con sus propios términos.
planName string?
status string? estado de sqlly.app en la última comprobación: active, grace, expired, revoked, domain_mismatch.
seats integer Usuarios concurrentes que permite la licencia.
sessionsPerSeat integer Pestañas de SQLly abiertas que puede tener un solo usuario.
instances integer Puentes que pueden estar activos a la vez (licencias conectadas; 0 sin conexión).
domain string? El dominio vinculado; los navegadores deben venir de él o de un subdominio.
periodEnd string? Fin del período pagado (ISO 8601).
graceEnd string? Se establece durante el periodo de gracia: cuando el puente deja de servir.
daysRemaining integer? Días completos hasta que el puente deje de funcionar.
lastCheckinAt string (date-time)?
staleAt string (date-time)? Cuándo se vuelve obsoleto el puente si no hay ninguna verificación con éxito (última concesión válida + 40 minutos).
licenseFile string? Sin conexión: el archivo de licencia en uso.
message string? La frase que ven los usuarios cuando algo va mal (también las cuentas regresivas de gracia).
fromCache boolean Verdadero cuando el puente se inició con la concesión en caché porque sqlly.app no estaba accesible.
features string[]

LinkLicenseRequest

CampoTipoDescripción
licenseKey * string Una clave que empieza por sqe_.

EngineInfo

CampoTipoDescripción
id string La engine valor para un documento de credencial.
name string
defaultPort integer
fileBased boolean server es una ruta de archivo y no se requiere iniciar sesión.
authentication string[] Aceptado authentication.type valores.

ProfileSummary

CampoTipoDescripción
id string
name string
connections integer Número de conexiones en el documento.
updatedAt string (date-time)

StoredProfile

CampoTipoDescripción
id string
name string
credentials CredentialDocument
updatedAt string (date-time)

PutProfileRequest

CampoTipoDescripción
name * string Nombre para mostrar, el que verán los usuarios en SQLly.
credentials * CredentialDocument

CredentialDocument

Un documento de credenciales de SQLly (el mismo formato que Archivo → Importar Conexiones de SQLly). Las claves desconocidas se tratan como errores, así que los errores tipográficos se notifican en vez de pasarse por alto. Referencia completa: sqlly.app/docs (Formato de archivo de credenciales).

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

Etiqueta

CampoTipoDescripción
name * string
color string #RGB, #RRGGBB o #RRGGBBAA.
image string Icono como URI de datos o base64 sin formato (PNG, JPEG, GIF, WebP, BMP, ICO, SVG; hasta 1 MB).
safety object Solo cambian los indicadores que enumeres.

SharedLogin

CampoTipoDescripción
name * string
username * string
password string

Conexión

CampoTipoDescripción
name * string
engine * string Un id de GET /manage/engines.
server * string Host, IP, host\instance o una ruta de archivo para SQLite/DuckDB.
port integer
database string
environment string local, dev, test, staging, production o sin establecer.
client string Un nombre de etiqueta de cliente.
project string Un nombre de etiqueta de proyecto.
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 Proxy integrado, con saltos ssh y kube.
masking object { include: [...], exclude: [...] } reglas de enmascaramiento de columnas.

Autenticación

CampoTipoDescripción
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 Nombre de un inicio de sesión compartido en sql_auth_accounts.
region string
profile string
token string

MintTokenRequest

CampoTipoDescripción
user * string Tu ID estable para el usuario (sin espacios en blanco). Los asientos se cuentan por cada usuario distinto.
profile * string Un ID de perfil.
ttlSeconds integer Duración del token; por defecto es --token-ttl-seconds (600) y se limita al rango de 10 s a 24 h.
open LaunchTab | LaunchTab[] Contexto de lanzamiento: una pestaña de consulta, o hasta 8, que SQLly abre al iniciar la sesión. La primera sesión que el token admite las recibe; las recargas y las sesiones posteriores no. Se valida contra el perfil en el momento de crearlo (400 invalid_open). Nada se ejecuta hasta que el usuario presiona Ejecutar. Guía: sqlly.app/docs/embedded/launch-context

LaunchTab

Una pestaña de consulta de un lanzamiento. Necesita un script, un connection, o ambos.

CampoTipoDescripción
connection string Una conexión del perfil del token, por nombre (sin distinguir mayúsculas de minúsculas, debe ser único) o por id. Es opcional cuando el perfil tiene una sola conexión; si hay varias y no se indica ninguna, la pestaña se abre sin vincular.
database string Base de datos a la que cambiar en vez de la predeterminada de la conexión.
title string El título de la pestaña.
script string El SQL a cargar, tal cual (máximo 256 KiB; CRLF se convierte a LF).
parameters object Valores para los @name parámetros, indexados por nombre (con o sin @). El tipo de un valor sin comillas se infiere (número entero → int, otro número → decimal, booleano → bool, cadena → text, nulo → empty); usa { type, value } para elegir. Los parámetros que el script no declara obtienen una línea -- sqlly param: línea; los valores aparecen en la franja de parámetros de SQLly y nunca los incrusta tu aplicación.
cursor LaunchCursor

LaunchParameterValue

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

LaunchCursor

Posición del cursor en script, empezando en 1; la columna cuenta caracteres y puede apuntar uno más allá del final de la línea.

CampoTipoDescripción
line integer
column integer

MintedToken

CampoTipoDescripción
token string
expiresAt string (date-time)
proxyUrl string
user string
profile string
seatsUsed integer Asientos en uso, incluido este usuario.
seats integer
openTabs integer Cuántas pestañas abrirá la sesión (0 sin contexto de inicio).

SeatsReport

CampoTipoDescripción
seats integer
seatsUsed integer
users UserSeat[]

UserSeat

CampoTipoDescripción
user string
activeSessions integer
tokens integer Tokens de lanzamiento sin caducar.
since string (date-time)

SolicitudDePruebaDeConexión

CampoTipoDescripción
credentials * CredentialDocument

ResultadoDePrueba

CampoTipoDescripción
ok boolean
elapsedMs integer
message string El mensaje del propio motor, sea de éxito o de fallo.

QueryStatus

running hasta que el motor responda; entonces completed, failed (ver error) o cancelled (por el usuario, o session closed).

Uno de: running completed failed cancelled

QueryEntry

Una solicitud auditada.

CampoTipoDescripción
id string El id de la solicitud del motor, único dentro de su sesión.
sessionId integer El id del puente para la sesión del navegador.
kind query | row-edit
at string (date-time) Cuándo llegó la solicitud al puente.
user string El id de usuario del token de lanzamiento.
profile string El id de perfil del token de lanzamiento.
profileName string
connection string El nombre de la conexión en el perfil.
server string
database string? La base de datos del perfil si este fija una; si no, la base de datos que indique la solicitud.
engine string El nombre para mostrar del motor.
sql string El texto SQL, o row edit: <op> para una edición de fila. Recortado a 64 KiB.
sqlTruncated boolean
status QueryStatus
durationMs integer? Nulo mientras se ejecuta.
error string? El error del motor para failed; session closed para una solicitud interrumpida por el fin de su sesión.

QueryListing

CampoTipoDescripción
enabled boolean Falso cuando el puente se ejecuta con --query-log false; entonces queries siempre está vacío.
queries QueryEntry[] Los más recientes primero.
total integer Entradas que coinciden con los filtros antes de limit se aplicó.
limit integer El tamaño de página aplicado (1-1000).

CreateLinkRequest

CampoTipoDescripción
name string Mostrado al propietario en la página de aprobación y en su página Embedded.
hostname string
appVersion string

CreateLinkResponse

CampoTipoDescripción
linkId string
code string Muestra esto al propietario para que pueda comprobar que coincide.
secret string Mantener en el servidor; recopila la clave.
linkUrl string Abre esto para que el propietario lo apruebe.
expiresAt string (date-time)
pollIntervalSeconds integer

LinkTokenRequest

CampoTipoDescripción
linkId * string
secret * string

LinkPending

CampoTipoDescripción
status pending
expiresAt string (date-time)

LinkApproved

CampoTipoDescripción
status approved
licenseKey string Devuelto exactamente una vez. Pásalo a PUT /manage/license.
keyId string
licenseId string
plan string Id del plan, o custom.
planName string
accountEmail string

* obligatorio