List Databases
List the managed databases of the active account, newest first. A database is a MariaDB database that belongs to the account: it has its own users and is connected to managed, full-stack and function apps, which then get DB_HOST … DATABASE_URL as environment variables. See Databases for the dashboard side (Storage → Databases).
The list also includes the database an app got from POST /v1/applications/{uuid}/database, named after the app. A database with no label (an older per-app database) shows its name inside MariaDB as its name.
Requires the caller's role to have Databases read, and a plan with managed databases (Team: 3 databases, Enterprise: 10). Every route of the Databases API is also on the agent plane under /v1/agent/databases (and /v1/agent/applications/{uuid}/database-connections) for account-scoped agent tokens, the way the ngris CLI calls the API.
Query parameters
search string
Case-insensitive substring of the name (or of the name inside MariaDB).
status string
provisioning | ready | failed | deleting. Exact match.connected "true" | "false"
true: only databases at least one application uses; false: only unused ones. Omit for all.page int
1-based page number. Default
1.page_size int
Items per page, at most
100. Default 25 (when you pass page alone, the API's default page size, 15).Response (200 OK)
databases array
Database objects (fields below).
total int
Databases matching the filters, across all pages.
page / page_size int
The page returned.
quota object
{used, limit}: the databases that count against the plan (creating or ready; a failed or deleting one doesn't count) and the plan's limit. limit is null when there is no cap.storage_limit_bytes int | null
The plan's storage per database, in bytes (Team 1 GiB, Enterprise 2 GiB);
null when the plan sets none. ngris doesn't measure database sizes yet.Errors
400
status must be one of provisioning, ready, failed, deleting or connected must be true or false.403
Insufficient permissions for this action (no Databases read), No active account for this request, or Managed databases are not available on your plan.503
databases_unavailable: every Databases route answers this until the feature's database migration is applied (it is applied on ngris).Request
curl "https://api.ngris.com/v1/databases?connected=true" \
-H "X-API-KEY: <your_api_key>"
Response — 200 OK
{
"databases": [
{
"uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
"name": "orders-db",
"engine": "mariadb",
"status": "ready",
"placement": "shared",
"db_name": "app_orders_db_k3x9q2tm",
"host": "mariadb-apps.ngris-appdb.svc.cluster.local",
"port": 3306,
"size_bytes": null,
"size_measured_at": null,
"quota_paused": false,
"connected_app_count": 1,
"user_count": 2,
"created_at": "2026-10-18T09:00:00Z",
"updated_at": "2026-10-18T09:00:05Z"
}
],
"total": 1,
"page": 1,
"page_size": 25,
"quota": { "used": 1, "limit": 3 },
"storage_limit_bytes": 1073741824
}
Response — 503 (before the migration)
{
"error": "Databases are not available yet: this feature is still being rolled out. Please try again later.",
"code": "databases_unavailable"
}
Get Database
Fetch one database with where apps reach it (host, port, name inside MariaDB — never a password), its users, its connections and the apps that use it. Requires Databases read.
Database object
uuid string (uuid)
The database's id.
name string
Your label (1–64 characters, unique in the account). A database with no label shows its name inside MariaDB.
engine string
mariadb, the only engine.status string
provisioning (being created) → ready; failed (delete it and create a new one); deleting.placement string
shared: the database lives on ngris's shared database server.db_name string
The name inside MariaDB,
app_ + the name in lowercase letters, digits and _ + _ + 8 generated characters. It never changes; an app gets it as DB_NAME.host / port string / int
The internal address apps on ngris connect to (
DB_HOST / DB_PORT). Nothing outside ngris can reach it.size_bytes / size_measured_at null
Always
null today: ngris doesn't measure database sizes yet.quota_paused bool
true when the account has more databases than its plan allows and this one is paused: its settings are read-only (409 quota_paused on rename, new users, password rotation and new connections); deleting it, its users, and disconnecting apps still work. quota_paused_at says since when.connected_app_count / user_count int
Applications using the database, and its users that aren't being deleted.
created_at / updated_at string (RFC 3339)
Timestamps.
Response (200 OK)
database object
The database object above.
users array
Its users, each with
used_by (the apps connected as it).connections array
Its connections to applications.
connected_apps array
The distinct apps using it,
{application_uuid, application_name}. An app bound to the database the older way, with no connection (an older per-app database), carries legacy: true: it can't be disconnected through the connections API.storage_limit_bytes int | null
The plan's storage per database, in bytes.
quota_paused_limit int
Only on a paused database: the plan's database limit.
Errors
403
No Databases read, no active account, or no managed databases on the plan.
404
database not found: no such database in the active account (another account's reads the same).503
databases_unavailable.Request
curl "https://api.ngris.com/v1/databases/019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18" \
-H "X-API-KEY: <your_api_key>"
Response — 200 OK
{
"database": {
"uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
"name": "orders-db",
"engine": "mariadb",
"status": "ready",
"placement": "shared",
"db_name": "app_orders_db_k3x9q2tm",
"host": "mariadb-apps.ngris-appdb.svc.cluster.local",
"port": 3306,
"size_bytes": null,
"size_measured_at": null,
"quota_paused": false,
"connected_app_count": 1,
"user_count": 1,
"created_at": "2026-10-18T09:00:00Z",
"updated_at": "2026-10-18T09:00:05Z"
},
"users": [
{
"uuid": "019c2a41-7d40-7e15-9b63-2f8c4d1a7e95",
"name": "app",
"db_user": "u_p7d2m1_app",
"access": "read_write",
"kind": "customer",
"status": "ready",
"created_at": "2026-10-18T09:00:00Z",
"updated_at": "2026-10-18T09:00:04Z",
"database_uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
"used_by": [
{ "application_uuid": "019be838-d261-7d9b-9499-71995a3a91c6", "application_name": "orders-api" }
]
}
],
"connections": [
{
"uuid": "019c2a71-9a2d-7d06-8e41-3f7b2c9d0a58",
"env_prefix": "",
"environment": "all",
"var_set": "standard",
"created_at": "2026-10-18T09:02:00Z",
"application_uuid": "019be838-d261-7d9b-9499-71995a3a91c6",
"application_name": "orders-api",
"database_uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
"database_name": "orders-db",
"database_user_uuid": "019c2a41-7d40-7e15-9b63-2f8c4d1a7e95",
"database_user_name": "app",
"env_names": ["DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD", "DATABASE_URL"]
}
],
"connected_apps": [
{ "application_uuid": "019be838-d261-7d9b-9499-71995a3a91c6", "application_name": "orders-api" }
],
"storage_limit_bytes": 1073741824
}