Web API Reference
Base URL
By default, DBX Web listens on port 4224:
http://localhost:4224When deployed behind a reverse-proxy subpath, set DBX_PUBLIC_BASE_PATH and prefix every route. For example, with /dbx:
https://example.com/dbx/api/auth/checkAll API routes are under /api.
Authentication
Protected routes require a session cookie named dbx_session.
Check Auth State
GET /api/auth/checkExample response:
{
"authenticated": false,
"required": true,
"setup_required": false
}| Field | Meaning |
|---|---|
required | Password protection is enabled |
setup_required | First-run password setup is still needed |
authenticated | Current request already has a valid session |
First-Run Setup
POST /api/auth/setup
Content-Type: application/json
{
"password": "your-password"
}Login
POST /api/auth/login
Content-Type: application/json
{
"password": "your-password"
}On success, the response sets Set-Cookie: dbx_session=.... Reuse that cookie on later requests.
Five consecutive login failures trigger an approximately 60-second lockout. Sessions live in the current Web process and require login again after restart. The cookie is HttpOnly, uses SameSite=Lax, and follows DBX_PUBLIC_BASE_PATH for its path.
Logout
POST /api/auth/logout
Cookie: dbx_session=...Environment Variables
| Variable | Purpose |
|---|---|
DBX_PASSWORD | Set an initial password at container startup |
DBX_DISABLE_PASSWORD=1 | Disable password protection entirely |
DBX_PORT | Change the listen port (default 4224) |
DBX_DATA_DIR | Data directory containing dbx.db |
DBX_PUBLIC_BASE_PATH | Serve DBX under a subpath such as /dbx |
DBX_MAX_UPLOAD_MB | Override the general request and uploaded-file limit; default 1024 MB. Multipart routes reserve fixed protocol overhead (set at least 4096 for a 4 GiB file) |
DBX_AGENT_DIR | Override the Web Agent/driver directory; defaults to agents under the data directory |
DBX_STATIC_DIR | Override the Web static asset directory |
RUST_LOG | Configure Rust backend log filtering; the default is dbx_web=info,tower_http=info |
RUST_BACKTRACE=1 | Include Rust backtraces when an error reports one |
Logging and Troubleshooting
DBX Web reads the standard RUST_LOG filter when it starts. For a focused diagnostic run, increase the Web and HTTP middleware targets without enabling every dependency:
RUST_LOG=dbx_web=debug,tower_http=info ./dbxSet RUST_BACKTRACE=1 as well when the error includes a Rust backtrace. If the problem is inside another DBX crate, add its target to the same filter, such as dbx_core, dbx_drivers, dbx_sql, dbx_plugin_runtime, dbx_ai_provider, or dbx_platform. RUST_LOG=debug enables a much broader and noisier filter. Logs are written to the process output; redirect that output when you need to save a diagnostic file.
Request Format
- Field naming follows each Rust request type. Some bodies use
camelCase, while connection configuration still containssnake_case; do not apply one naming convention to the whole API. GETquery parameters commonly usesnake_case, such asconnection_id, but the current route implementation remains authoritative.- Errors usually return JSON with an
errorfield and an HTTP status code. - Long-running export, import, transfer, SQL-file, and AI operations commonly use a start request plus SSE progress and cancel/download routes rather than one synchronous response.
Only the data-grid extractor currently exposes a tested, scoped OpenAPI document at /api/query/data-grid-extractor-openapi.json. It does not cover the complete DBX Web API or version the other routes.
Connection APIs
List Connections
GET /api/connection/list
Cookie: dbx_session=...Returns saved connection profiles. Secrets such as passwords are stored separately from the returned JSON.
Save Connections
Connections are upserted by id: connections the request does not mention are left untouched, so several
clients can share one server without deleting each other's profiles. Deletions are explicit through the
optional removedIds array.
POST /api/connection/save
Content-Type: application/json
Cookie: dbx_session=...
{
"configs": [
{
"name": "local-mysql",
"db_type": "mysql",
"host": "127.0.0.1",
"port": 3306,
"username": "root",
"database": "app"
}
],
"removedIds": ["connection-to-delete"]
}Test Connection
POST /api/connection/test
Content-Type: application/json
{
"config": {
"name": "temp",
"db_type": "mysql",
"host": "127.0.0.1",
"port": 3306,
"username": "root",
"database": "app"
}
}Connect
Most data APIs expect the target connection to be active first.
POST /api/connection/connect
Content-Type: application/json
{
"config": {
"id": "connection-id",
"name": "local-mysql",
"db_type": "mysql",
"host": "127.0.0.1",
"port": 3306,
"username": "root",
"database": "app"
}
}Check Health
POST /api/connection/check-health
Content-Type: application/json
{
"connectionId": "connection-id"
}Schema APIs
List Tables
GET /api/schema/tables?connection_id=CONNECTION_ID&database=app&schema=
Cookie: dbx_session=...List Columns
GET /api/schema/columns?connection_id=CONNECTION_ID&database=app&schema=&table=users
Cookie: dbx_session=...Read Oracle-Family Triggers
To find triggers without knowing their owning table, use the object list with a trigger type filter. Search and type filters are applied before paging in the exact metadata adapters.
GET /api/schema/objects?connection_id=CONNECTION_ID&database=demo&schema=APP&object_types=TRIGGER&filter=audit&limit=100&offset=0&identity_mode=exact
Cookie: dbx_session=...Use the owning object's schema and name to list its triggers. The returned trigger owner can differ from that schema.
GET /api/schema/triggers?connection_id=CONNECTION_ID&database=demo&schema=DATA&table=ORDERS&identity_mode=exact
Cookie: dbx_session=...Fetch the full definition using the trigger's owner and name. On this route,
table is the source object name, not its parent table.
GET /api/schema/object-source?connection_id=CONNECTION_ID&database=demo&schema=APP&table=AUDIT_ORDERS&object_type=TRIGGER&identity_mode=exact
Cookie: dbx_session=...These three routes accept optional identity_mode=exact and catalog query
parameters. Omitting identity_mode retains the existing metadata behavior.
Exact reads preserve raw owner/name values; URL-encode spaces, quotes, and other
reserved characters rather than trimming or changing their case. catalog is
forwarded to the selected metadata provider; it does not replace schema.
Trigger summaries and source responses may contain trigger.oracle_metadata
(oracle_metadata directly on entries returned by /schema/triggers). Version
1 includes the verified engine, exact owner/name, scope, independent parent,
string-valued object ID, and per-field reads states. enabled is the trigger
state; valid is the independently read object validity. Schema/database scopes
do not have an invented table parent.
An exact source lookup that succeeds with no visible matching trigger returns
reads.identity.state="empty" with the verified engine and raw target. It means
empty within current visibility, not global absence. Query failures and legacy
providers cannot supply that proof; creation still uses CREATE without REPLACE.
Source metadata additionally reports definition origin/format/completeness and
compilation errors with line/position. A null or absent error list is unknown,
not an empty successful read. Failed or incomplete reads cannot supply a write
baseline; keep the draft, restore dictionary access or update the provider, and
read again. Old Agents/plugins that omit the metadata contract remain usable in
their original mode but do not prove exact identity. The source text can include
a same-target state appendix from DBMS_METADATA; it is export text, not an
arbitrary multi-statement save payload.
Other schema routes include:
/api/schema/databases/api/schema/schemas/api/schema/indexes/api/schema/foreign-keys/api/schema/ddl
SQL Query APIs
Execute One Statement
POST /api/query/execute
Content-Type: application/json
{
"connectionId": "connection-id",
"database": "app",
"sql": "select id, name from users limit 10"
}Example response shape:
{
"columns": ["id", "name"],
"rows": [[1, "Ada"], [2, "Lin"]]
}Related routes:
| Route | Purpose |
|---|---|
/api/query/execute-multi | Execute multiple result sets in one request |
/api/query/execute-batch | Execute a list of statements |
/api/query/cancel | Cancel a running query |
/api/query/build-table-select-sql | Build a table browse query |
Prepare One Oracle-Family Trigger Definition
POST /api/query/prepare-oracle-trigger-sql accepts { "input": ... } with
databaseType (oracle, oceanbase-oracle, or dameng), raw owner/name,
source, and purpose (inspect, create, or replace). It returns a single
normalized definition, the parsed header, and independent inline/export
enabled states. This route only prepares SQL; execute through the normal query
route after checking the current object, privileges, and concurrent changes.
comparisonSource is for readback comparison only. It canonicalizes the known
declaration wrapper while preserving the remaining header, body, comments, and
literal newlines. Execute definition, not this comparison form.
structuredEditable reports whether the complete definition's header can be represented without loss by the timing/event/body form. A false or absent value requires the complete-source editor for structural changes; a plain TRIGGER_BODY alone does not establish this capability.
For create/replace, supply binding with the verified scope
(TABLE, VIEW, SCHEMA, DATABASE, or TIMER), parent owner/name where
applicable, and pluggable for a verified Oracle container scope. Omitted ON
qualifiers are filled only from that binding. Replace also requires the current
desired enabled state. Create produces CREATE without OR REPLACE. Oracle and
verified OceanBase preserve state in the definition; DM's
requiresStateRestore indicates a separate native state step to preview and
verify. allowExportAppendix is only for inspecting trusted metadata exports;
write purposes reject it and any extra SQL.
Redis APIs
Redis browser and command execution use dedicated routes.
POST /api/redis/execute-command
Content-Type: application/json
{
"connectionId": "redis-id",
"db": 0,
"command": "GET mykey"
}Other common Redis routes:
/api/redis/scan-keys/api/redis/get-value/api/redis/set-string/api/redis/delete-key
MongoDB APIs
MongoDB routes are POST endpoints with JSON bodies.
List Collections
POST /api/mongo/list-collections
Content-Type: application/json
{
"connectionId": "mongo-id",
"database": "app"
}Find Documents
POST /api/mongo/find-documents
Content-Type: application/json
{
"connectionId": "mongo-id",
"database": "app",
"collection": "users",
"skip": 0,
"limit": 20,
"filter": "{}"
}Other MongoDB routes include aggregate-documents, insert-documents, update-documents, and delete-documents.
MCP and CLI Integration
For automation, these packages are usually easier to maintain than calling the Web API directly:
- MCP: @dbx-app/mcp-server
- CLI: @dbx-app/cli
When MCP runs against a deployed Web instance, set:
{
"env": {
"DBX_WEB_URL": "http://localhost:4224",
"DBX_WEB_PASSWORD": "your-password"
}
}The MCP server handles login and session cookies for you.
CLI supports the same DBX_WEB_URL and DBX_WEB_PASSWORD variables. Both integrations reuse server-side connections, drivers, read-only protection, production protection, and database privileges, making them easier to maintain across DBX upgrades than copied internal route payloads.
Writes, Safety, and File Boundaries
- API authentication proves only that the request belongs to a logged-in session; it does not replace database privileges
- Query, import, and transfer paths continue to enforce connection read-only protection, while production and SQL-risk policy apply in their corresponding core paths
- Browser-selected table-import and SQL files are uploaded into server temporary storage, not read from arbitrary client paths
- Web exports create a temporary server file, return it through a download route, and then clean it up
- Reverse proxies should preserve cookies and SSE streaming, allow appropriate long-running timeouts, and limit public exposure
Example Scripts
See the repository examples:
Route Groups
The Web backend exposes many more routes for the UI, including:
/api/export/*for exports and downloads/api/import/*for table imports/api/transfer/*for data transfer jobs/api/ai/*for the built-in AI assistant/api/agents/*and/api/jdbc/*for driver management/api/history/*and/api/saved-sql/*for editor state
Browse crates/dbx-web/src/main.rs in the repository for the full route list.