Web API Reference

This API powers the DBX Web UI and internal tooling such as the MCP Web backend. It is not a separate public integration contract. Endpoints and payloads may change between releases. For scripting and agent workflows, prefer @dbx-app/cli or @dbx-app/mcp-server when possible.

Base URL

By default, DBX Web listens on port 4224:

http://localhost:4224

When 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/check

All API routes are under /api.

Authentication

Protected routes require a session cookie named dbx_session.

Check Auth State

GET /api/auth/check

Example 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"
}

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

Request Format

Field naming follows each Rust request type. Some bodies use camelCase, while connection configuration still contains snake_case; do not apply one naming convention to the whole API.
GET query parameters commonly use snake_case, such as connection_id, but the current route implementation remains authoritative.
Errors usually return JSON with an error field 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

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"
    }
  ]
}

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=...

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

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.

Web API Reference

On this page