# Web API Reference > Internal HTTP APIs used by the DBX Web and Docker UI, including authentication, queries, background jobs, uploads, and downloads. Source: https://dbxio.com/en/docs/web-api Language: en Relative links resolve against https://dbxio.com/en/docs/web-api. 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](/en/docs/cli) or [@dbx-app/mcp-server](/en/docs/mcp) when possible. ## Base URL By default, DBX Web listens on port `4224`: ```text http://localhost:4224 ``` When deployed behind a reverse-proxy subpath, set `DBX_PUBLIC_BASE_PATH` and prefix every route. For example, with `/dbx`: ```text 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 ```http GET /api/auth/check ``` Example response: ```json { "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 ```http POST /api/auth/setup Content-Type: application/json { "password": "your-password" } ``` ### Login ```http 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 ```http 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: ```bash RUST_LOG=dbx_web=debug,tower_http=info ./dbx ``` Set `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 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 ```http 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. ```http 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 ```http 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. ```http 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 ```http POST /api/connection/check-health Content-Type: application/json { "connectionId": "connection-id" } ``` ## Schema APIs ### List Tables ```http GET /api/schema/tables?connection_id=CONNECTION_ID&database=app&schema= Cookie: dbx_session=... ``` ### List Columns ```http 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 ```http POST /api/query/execute Content-Type: application/json { "connectionId": "connection-id", "database": "app", "sql": "select id, name from users limit 10" } ``` Example response shape: ```json { "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. ```http 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 ```http POST /api/mongo/list-collections Content-Type: application/json { "connectionId": "mongo-id", "database": "app" } ``` ### Find Documents ```http 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](/en/docs/mcp) * CLI: [@dbx-app/cli](/en/docs/cli) When MCP runs against a deployed Web instance, set: ```json { "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: * [examples/web-api/automation.sh](https://github.com/t8y2/dbx/tree/main/examples/web-api/automation.sh) * [examples/docker/docker-compose.yml](https://github.com/t8y2/dbx/tree/main/examples/docker/docker-compose.yml) * [examples/cli/basic-workflow.sh](https://github.com/t8y2/dbx/tree/main/examples/cli/basic-workflow.sh) ## 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.