API Reference

Databases

API reference for MariaDB databases and database users, linking them to apps and websites, the SQL interface and one-click phpMyAdmin sign-in.

Last updated

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

MethodPathDescription
GET/api/v1/databasesList databases
POST/api/v1/databasesCreate a database
GET/api/v1/databases/:idGet a database
PATCH/api/v1/databases/:idLink a database
DELETE/api/v1/databases/:idDelete a database
POST/api/v1/databases/:id/retryRetry creating a database
POST/api/v1/databases/:id/tablesList tables
POST/api/v1/databases/:id/rowsBrowse a table
POST/api/v1/databases/:id/queryRun SQL
POST/api/v1/databases/:id/phpmyadminOpen in phpMyAdmin
GET/api/v1/database-usersList database users
POST/api/v1/database-usersCreate a database user
PATCH/api/v1/database-users/:idUpdate a database user
DELETE/api/v1/database-users/:idDelete a database user
POST/api/v1/database-users/:id/passwordReveal 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

GET/api/v1/databases
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.read
Token scope
read

Databases, by name. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
searchstringNoMatches the name.
serverIdstringNoDatabases on one server.
applicationIdstringNoDatabases linked to one app.
websiteIdstringNoDatabases linked to one website.
sortstringNoname (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

POST/api/v1/databases
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

Creates 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

FieldTypeRequiredDescription
serverIdstringYesThe server to create it on.
namestringYes2 to 64 lowercase letters, digits and underscores, starting with a letter. Not a name reserved by the database server.
applicationIdstring or nullNoThe app that uses it, on the same server and account.
websiteIdstring or nullNoThe website that uses it, so its backups can include it.
createUserbooleanNoAlso create a user. Default true.
usernamestringNo2 to 32 lowercase letters, digits and underscores. Defaults to the database name.
privilegesstringNoThe user's access: all (default) or readonly.
addToAppEnvbooleanNoAdd 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

StatusCodeWhen
403FORBIDDENAdding to an app's environment without applications.manage.
409SERVER_NOT_READYThe server has no connected agent yet.
409DATABASE_SERVER_NOT_INSTALLEDInstall MariaDB on the server first.
409AGENT_OUTDATEDThe agent is too old to manage databases.
409QUOTA_REACHEDA hosting customer's plan allows no more databases or users.
422VALIDATION_ERRORAn 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

GET/api/v1/databases/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.read
Token scope
read

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

PATCH/api/v1/databases/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

Links 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

FieldTypeRequiredDescription
applicationIdstring or nullNoThe app that uses it.
websiteIdstring or nullNoThe 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

StatusCodeWhen
422VALIDATION_ERRORNothing to update, or the app or website is not on the same server and account.

Delete a database

DELETE/api/v1/databases/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

Drops 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

StatusCodeWhen
409DATABASE_BUSYAnother change is running.

Retry creating a database

POST/api/v1/databases/:id/retry
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

Queues CREATE_DATABASE again for a database whose creation failed.

Response 202 Accepted with { database, job }.

Errors

StatusCodeWhen
409DATABASE_READYThe 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

POST/api/v1/databases/:id/tables
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

Example 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

POST/api/v1/databases/:id/rows
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

One page of a table's rows, with its columns, indexes and CREATE statement.

Request body

FieldTypeRequiredDescription
tablestringYesThe table or view.
pageintegerNoFrom 1. Default 1.
pageSizeintegerNo1 to 500. Default 50.
orderBystringNoA column to sort by.
orderstringNoasc (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

POST/api/v1/databases/:id/query
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

Runs 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

FieldTypeRequiredDescription
sqlstringYesUp to 100000 characters.
allowChangesbooleanNoRun 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

POST/api/v1/databases/:id/phpmyadmin
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

One-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

StatusCodeWhen
409PHPMYADMIN_NOT_SET_UPphpMyAdmin is not set up on this server.
409DATABASE_NOT_READYThe database is not ready on its server.

List database users

GET/api/v1/database-users
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.read
Token scope
read

Users, by username, each with the databases it can reach. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
searchstringNoMatches the username.
serverIdstringNoUsers on one server.
sortstringNousername (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

POST/api/v1/database-users
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

Creates a user (CREATE_DATABASE_USER) with access to the given databases on the same server.

Request body

FieldTypeRequiredDescription
serverIdstringYesThe server.
usernamestringYes2 to 32 lowercase letters, digits and underscores, starting with a letter.
passwordstringNo12 to 72 letters, digits or the symbols ! # % + , . : = ? @ ^ _ ~ -. Generated when left out.
privilegesstringNoall (default) or readonly.
databaseIdsstring[]NoUp 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

StatusCodeWhen
409SERVER_NOT_READY, DATABASE_SERVER_NOT_INSTALLED, AGENT_OUTDATEDAs for Create a database.
409QUOTA_REACHEDA hosting customer's plan allows no more database users.
422VALIDATION_ERRORAn invalid or taken username, an invalid password, or a database on another server.

Update a database user

PATCH/api/v1/database-users/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

Changes 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

FieldTypeRequiredDescription
passwordstringNoA new password, with the same rules as for create.
generatePasswordbooleanNoGenerate a new password and return it once.
privilegesstringNoall or readonly.
databaseIdsstring[]NoUp 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

StatusCodeWhen
409DATABASE_USER_NOT_READYThe user was never created on the server. Delete it and create it again.
409DATABASE_BUSYAnother change to this user is running.
422VALIDATION_ERRORNothing to update, both password fields, or an invalid value.

Delete a database user

DELETE/api/v1/database-users/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

Drops 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

POST/api/v1/database-users/:id/password
Auth
Session cookie (+ CSRF token) or API token
Permission
databases.manage
Token scope
manage

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