Databases
API reference for MariaDB databases and database users, linking them to apps and websites, the SQL interface and one-click phpMyAdmin sign-in.
Databases and database users live on the MariaDB server of one of your servers (the one the installer set up for websites and apps, on port 3306). Passwords are generated for you, stored encrypted, and added to an app's environment in one step. See Databases.
Hosting customers can use these endpoints for their own databases, within their plan.
How changes work
Creating, deleting and changing databases and users returns 202 Accepted with the record and the job that carries the change out. A record's status is creating, updating or deleting while its job runs; another change meanwhile answers 409 DATABASE_BUSY with details.jobId. MariaDB must be installed on the server.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/databases | List databases |
| POST | /api/v1/databases | Create a database |
| GET | /api/v1/databases/:id | Get a database |
| PATCH | /api/v1/databases/:id | Link a database |
| DELETE | /api/v1/databases/:id | Delete a database |
| POST | /api/v1/databases/:id/retry | Retry creating a database |
| POST | /api/v1/databases/:id/tables | List tables |
| POST | /api/v1/databases/:id/rows | Browse a table |
| POST | /api/v1/databases/:id/query | Run SQL |
| POST | /api/v1/databases/:id/phpmyadmin | Open in phpMyAdmin |
| GET | /api/v1/database-users | List database users |
| POST | /api/v1/database-users | Create a database user |
| PATCH | /api/v1/database-users/:id | Update a database user |
| DELETE | /api/v1/database-users/:id | Delete a database user |
| POST | /api/v1/database-users/:id/password | Reveal a user's password |
The database object
{
"id": "8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9",
"serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
"serverName": "web-1",
"customerId": null,
"engine": "mariadb",
"name": "shop",
"charset": "utf8mb4",
"collation": "utf8mb4_unicode_ci",
"status": "active",
"sizeBytes": 52428800,
"sizeCheckedAt": "2026-11-10T11:00:00.000Z",
"application": { "id": "5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c", "name": "api" },
"website": null,
"users": [{ "id": "b1a2c3d4-…", "username": "shop", "privileges": "all" }],
"lastJobId": "…",
"lastError": null,
"createdAt": "2026-11-02T09:10:00.000Z",
"updatedAt": "2026-11-02T09:10:20.000Z"
}status is creating, active, updating, deleting or failed. application and website are the app and website that use the database; a website's backups can include its linked databases.
The database user object
{
"id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
"serverName": "web-1",
"customerId": null,
"engine": "mariadb",
"username": "shop",
"privileges": "all",
"status": "active",
"hosts": ["localhost", "127.0.0.1"],
"databases": [{ "id": "8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9", "name": "shop" }],
"lastJobId": "…",
"lastError": null,
"createdAt": "2026-11-02T09:10:00.000Z",
"updatedAt": "2026-11-02T09:10:20.000Z"
}privileges is all (read, write and change the structure) or readonly (SELECT only). Users connect from the server itself, by socket or TCP.
List databases
/api/v1/databasesDatabases, by name. Supports the list parameters.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Matches the name. |
serverId | string | No | Databases on one server. |
applicationId | string | No | Databases linked to one app. |
websiteId | string | No | Databases linked to one website. |
sort | string | No | name (default, ascending), createdAt or size. |
Example request
curl "https://panel.example.com/api/v1/databases?serverId=1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.databases.list({ serverId });Response 200 OK: { items: [database], pagination }.
Create a database
/api/v1/databasesCreates a database (CREATE_DATABASE) and, by default, a user with access to it, named like the database. The user's generated password is returned only in this response. With applicationId and addToAppEnv (the default), the connection settings are added to the app's environment as DATABASE_URL, DB_HOST, DB_PORT, DB_NAME, DB_USER and DB_PASSWORD, only those it does not have yet (needs applications.manage).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
serverId | string | Yes | The server to create it on. |
name | string | Yes | 2 to 64 lowercase letters, digits and underscores, starting with a letter. Not a name reserved by the database server. |
applicationId | string or null | No | The app that uses it, on the same server and account. |
websiteId | string or null | No | The website that uses it, so its backups can include it. |
createUser | boolean | No | Also create a user. Default true. |
username | string | No | 2 to 32 lowercase letters, digits and underscores. Defaults to the database name. |
privileges | string | No | The user's access: all (default) or readonly. |
addToAppEnv | boolean | No | Add the connection settings to the app. Default true. |
Example request
curl https://panel.example.com/api/v1/databases \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"serverId":"1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b","name":"shop","applicationId":"5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c"}'const { database, user, password, envAdded } = await panel.databases.create({
serverId,
name: 'shop',
applicationId: appId,
});Response 202 Accepted
{
"success": true,
"data": {
"database": { "id": "8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9", "name": "shop", "status": "creating" },
"job": { "id": "…", "type": "CREATE_DATABASE", "status": "queued" },
"user": { "id": "b1a2c3d4-…", "username": "shop", "privileges": "all", "status": "creating" },
"password": "k2Vb9…",
"envAdded": ["DATABASE_URL", "DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"]
},
"message": "Creating the database on the server",
"requestId": "…"
}user and password are null when no user was created. Apply the app's settings (or deploy it) for new environment variables to take effect.
Errors
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | Adding to an app's environment without applications.manage. |
| 409 | SERVER_NOT_READY | The server has no connected agent yet. |
| 409 | DATABASE_SERVER_NOT_INSTALLED | Install MariaDB on the server first. |
| 409 | AGENT_OUTDATED | The agent is too old to manage databases. |
| 409 | QUOTA_REACHED | A hosting customer's plan allows no more databases or users. |
| 422 | VALIDATION_ERROR | An invalid or reserved name, a name already used on the server, or an app or website not on the same server and account. |
Get a database
/api/v1/databases/:idExample request
curl https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9 \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const database = await panel.databases.get(databaseId);Response 200 OK with the database object. 404 NOT_FOUND when there is no such database, or it is not yours.
Link a database
/api/v1/databases/:idLinks the database to the app and the website that use it, on the same server and account. null unlinks; a field left out keeps its link. Nothing changes on the server.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
applicationId | string or null | No | The app that uses it. |
websiteId | string or null | No | The website that uses it. |
Example request
curl -X PATCH https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9 \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"websiteId":"0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a"}'const { database } = await panel.databases.update(databaseId, { websiteId });Response 200 OK with { database }, message Saved.
Errors
| Status | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | Nothing to update, or the app or website is not on the same server and account. |
Delete a database
/api/v1/databases/:idDrops the database on the server (DELETE_DATABASE). Users stay; delete them separately.
Example request
curl -X DELETE https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9 \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { job } = await panel.databases.remove(databaseId);Response 202 Accepted with { database, job }.
Errors
| Status | Code | When |
|---|---|---|
| 409 | DATABASE_BUSY | Another change is running. |
Retry creating a database
/api/v1/databases/:id/retryQueues CREATE_DATABASE again for a database whose creation failed.
Response 202 Accepted with { database, job }.
Errors
| Status | Code | When |
|---|---|---|
| 409 | DATABASE_READY | The database already exists on its server. |
The SQL interface
List tables, Browse a table and Run SQL power the panel's database page. Each queues a routine job; the result arrives in the job's output. The agent runs them as an account that can reach only this database, read-only unless you allow changes. Statements stop after 30 seconds, results are cut at 1000 rows, and long cells at 5000 characters. All three need databases.manage and a database that is not being created, deleted or failed (409 DATABASE_NOT_READY). See SQL client.
List tables
/api/v1/databases/:id/tablesExample request
curl -X POST https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9/tables \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.request('POST', `/databases/${databaseId}/tables`);
const { job: done } = await panel.jobs.wait(job.id, { intervalMs: 500 });Response 202 Accepted with the job. Its output:
{
"name": "shop",
"tables": [
{
"name": "orders",
"type": "table",
"engine": "InnoDB",
"rowEstimate": 12840,
"dataBytes": 2637824,
"indexBytes": 1589248,
"collation": "utf8mb4_unicode_ci",
"comment": null,
"updatedAt": "2026-11-10 11:28:04"
}
]
}Browse a table
/api/v1/databases/:id/rowsOne page of a table's rows, with its columns, indexes and CREATE statement.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
table | string | Yes | The table or view. |
page | integer | No | From 1. Default 1. |
pageSize | integer | No | 1 to 500. Default 50. |
orderBy | string | No | A column to sort by. |
order | string | No | asc (default) or desc. |
Example request
curl https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9/rows \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"table":"orders","pageSize":20,"orderBy":"id","order":"desc"}'Response 202 Accepted with the job. Its output:
{
"name": "shop",
"table": "orders",
"columns": [
{ "name": "id", "type": "int(10) unsigned", "nullable": false, "key": "PRI", "default": null, "extra": "auto_increment", "comment": null }
],
"indexes": [{ "name": "PRIMARY", "unique": true, "type": "BTREE", "columns": ["id"] }],
"isView": false,
"createStatement": "CREATE TABLE `orders` (…)",
"page": 1,
"pageSize": 20,
"orderBy": "id",
"order": "desc",
"rows": [["12840", "…"]],
"hasMore": true,
"truncated": false
}Run SQL
/api/v1/databases/:id/queryRuns one or more statements. Without allowChanges they run read-only; statements that change data or structure are refused by the database server, and the error carries a hint. Queries run with allowChanges are recorded in the audit log (the first 1000 characters).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
sql | string | Yes | Up to 100000 characters. |
allowChanges | boolean | No | Run with write access. Default false. |
Example request
curl https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9/query \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"sql":"SELECT status, COUNT(*) AS n FROM orders GROUP BY status;"}'const job = await panel.request('POST', `/databases/${databaseId}/query`, {
body: { sql: 'SELECT status, COUNT(*) AS n FROM orders GROUP BY status;' },
});
const { job: done } = await panel.jobs.wait(job.id, { intervalMs: 500 });
console.log(done.output.statements, done.output.error);Response 202 Accepted with the job. Its output has name, allowChanges, elapsedMs, one entry per statement in statements (each with its sql and its result), and error when a statement failed: { code, sqlState, line, message }, plus hint for a change refused in read-only mode.
Open in phpMyAdmin
/api/v1/databases/:id/phpmyadminOne-click phpMyAdmin sign-in. The agent leaves a one-time ticket, valid for two minutes, for a fresh token; open phpMyAdmin with the token to be signed in as the database's own full-access account. Only the token's SHA-256 goes into the job; the token itself is returned only to you. phpMyAdmin must be set up on the server (PHPMYADMIN_SETUP). See phpMyAdmin.
Response 202 Accepted
{
"success": true,
"data": {
"job": { "id": "…", "type": "PHPMYADMIN_SIGNON", "status": "queued" },
"token": "…",
"phpmyadmin": { "port": 8081, "domain": null, "host": "203.0.113.10", "isLocal": false }
},
"message": "OK",
"requestId": "…"
}Wait for the job to succeed before opening phpMyAdmin with the token.
Errors
| Status | Code | When |
|---|---|---|
| 409 | PHPMYADMIN_NOT_SET_UP | phpMyAdmin is not set up on this server. |
| 409 | DATABASE_NOT_READY | The database is not ready on its server. |
List database users
/api/v1/database-usersUsers, by username, each with the databases it can reach. Supports the list parameters.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Matches the username. |
serverId | string | No | Users on one server. |
sort | string | No | username (default, ascending) or createdAt. |
Example request
curl https://panel.example.com/api/v1/database-users \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.databases.users.list();Response 200 OK: { items: [user], pagination }.
Create a database user
/api/v1/database-usersCreates a user (CREATE_DATABASE_USER) with access to the given databases on the same server.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
serverId | string | Yes | The server. |
username | string | Yes | 2 to 32 lowercase letters, digits and underscores, starting with a letter. |
password | string | No | 12 to 72 letters, digits or the symbols ! # % + , . : = ? @ ^ _ ~ -. Generated when left out. |
privileges | string | No | all (default) or readonly. |
databaseIds | string[] | No | Up to 50 databases on the same server. |
Example request
curl https://panel.example.com/api/v1/database-users \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"serverId":"1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b","username":"reports","privileges":"readonly","databaseIds":["8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9"]}'const { user, password } = await panel.databases.users.create({
serverId,
username: 'reports',
privileges: 'readonly',
databaseIds: [databaseId],
});Response 202 Accepted with { user, job, password }. password is the generated password, shown once, or null when you gave one.
Errors
| Status | Code | When |
|---|---|---|
| 409 | SERVER_NOT_READY, DATABASE_SERVER_NOT_INSTALLED, AGENT_OUTDATED | As for Create a database. |
| 409 | QUOTA_REACHED | A hosting customer's plan allows no more database users. |
| 422 | VALIDATION_ERROR | An invalid or taken username, an invalid password, or a database on another server. |
Update a database user
/api/v1/database-users/:idChanges a user's password, access or databases (UPDATE_DATABASE_USER). databaseIds replaces the list. Send at least one field, and not both password and generatePassword.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
password | string | No | A new password, with the same rules as for create. |
generatePassword | boolean | No | Generate a new password and return it once. |
privileges | string | No | all or readonly. |
databaseIds | string[] | No | Up to 50 databases on the same server. |
Example request
curl -X PATCH https://panel.example.com/api/v1/database-users/b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"generatePassword":true}'const { password } = await panel.databases.users.update(userId, { generatePassword: true });Response 202 Accepted with { user, job, password }. password is set only with generatePassword.
Errors
| Status | Code | When |
|---|---|---|
| 409 | DATABASE_USER_NOT_READY | The user was never created on the server. Delete it and create it again. |
| 409 | DATABASE_BUSY | Another change to this user is running. |
| 422 | VALIDATION_ERROR | Nothing to update, both password fields, or an invalid value. |
Delete a database user
/api/v1/database-users/:idDrops the user on the server (DELETE_DATABASE_USER). Its databases stay.
Example request
curl -X DELETE https://panel.example.com/api/v1/database-users/b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.databases.users.remove(userId);Response 202 Accepted with { user, job }.
Reveal a user's password
/api/v1/database-users/:id/passwordThe user's current password and how to connect, decrypted on request. Every reveal is recorded in the audit log.
Example request
curl -X POST https://panel.example.com/api/v1/database-users/b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/password \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { connectionUrl } = await panel.databases.users.password(userId);Response 200 OK
{
"success": true,
"data": {
"username": "shop",
"password": "k2Vb9…",
"host": "127.0.0.1",
"port": 3306,
"connectionUrl": "mysql://shop:k2Vb9…@127.0.0.1:3306/shop"
},
"message": "OK",
"requestId": "…"
}connectionUrl names the user's first database, or is null when it has none.
Applications
API reference for Node.js, Python, Go and Ruby apps deployed from Git, their deployments, environment, scaling and push-to-deploy hooks, and the app installer.
Containers
API reference for Docker containers - deploying, changing, redeploying and removing containers, any container or image on a server, and Docker itself.