Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/metabase/metabase/llms.txt

Use this file to discover all available pages before exploring further.

The Database API allows you to manage database connections, browse schemas and tables, and access metadata. This API includes 25 endpoints for comprehensive database management.

​
List databases

Get a list of all databases the current user has access to. 
GET /api/database

curl -X GET \
  https://your-metabase.com/api/database \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Response

Returns an array of database objects with connection details and metadata. 
{
  "data": [
    {
      "id": 1,
      "name": "Sample Database",
      "engine": "postgres",
      "created_at": "2024-01-15T10:00:00Z",
      "is_sample": false,
      "features": ["basic-aggregations", "nested-queries"]
    }
  ]
}

​
Get database

Get details about a specific database. 
GET /api/database/{id}

curl -X GET \
  https://your-metabase.com/api/database/1 \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Parameters

​
id
integer
required
Database ID

​
Response

​
id
integer
Database ID
​
name
string
Database name
​
engine
string
Database engine (postgres, mysql, h2, etc.)
​
details
object
Connection details (host, port, dbname, etc.)
​
features
array
Supported database features

​
Create database

Add a new database connection. 
POST /api/database

curl -X POST \
  https://your-metabase.com/api/database \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "name": "Production DB",
    "engine": "postgres",
    "details": {
      "host": "localhost",
      "port": 5432,
      "dbname": "production",
      "user": "metabase",
      "password": "secret"
    }
  }'

​
Request body

​
name
string
required
Display name for the database
​
engine
string
required
Database engine type (postgres, mysql, h2, mongo, etc.)
​
details
object
required
Connection details specific to the database engineCommon fields:
  • host - Database host
  • port - Database port
  • dbname - Database name
  • user - Username
  • password - Password
​
is_full_sync
boolean
Whether to perform a full sync (default: true)
​
schedules
object
Sync and cache field values schedules

​
Update database

Update an existing database connection. 
PUT /api/database/{id}

curl -X PUT \
  https://your-metabase.com/api/database/1 \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "name": "Updated Database Name",
    "details": {
      "host": "new-host.example.com"
    }
  }'

​
Parameters

​
id
integer
required
Database ID

​
Request body

All fields are optional. Only include fields you want to update.
​
name
string
Database display name
​
details
object
Connection details to update
​
is_full_sync
boolean
Enable or disable full sync

​
Delete database

Permanently delete a database connection. 
DELETE /api/database/{id}

curl -X DELETE \
  https://your-metabase.com/api/database/1 \
  -H 'X-Metabase-Session: SESSION_TOKEN'
Deleting a database will also delete all questions, dashboards, and other content that depends on it. This action cannot be undone.

​
List schemas

Get all schemas for a database. 
GET /api/database/{id}/schemas

curl -X GET \
  https://your-metabase.com/api/database/1/schemas \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Response

Returns an array of schema names. 
["public", "analytics", "staging"]

​
List tables

Get all tables in a database or schema. 
GET /api/database/{id}/metadata

curl -X GET \
  https://your-metabase.com/api/database/1/metadata \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Response

​
tables
array
Array of table objects with fields and metadata
​
fields
array
Array of field objects across all tables

​
Get table metadata

Get detailed metadata for a specific table including fields, field types, and relationships. 
GET /api/database/{id}/metadata
Query parameters can filter to specific tables or schemas.

​
Sync database schema

Trigger a manual sync of the database schema. 
POST /api/database/{id}/sync_schema

curl -X POST \
  https://your-metabase.com/api/database/1/sync_schema \
  -H 'X-Metabase-Session: SESSION_TOKEN'
Schema syncs run automatically on a schedule, but you can trigger a manual sync to immediately pick up schema changes.

​
Rescan field values

Rescan and cache field values for a database. 
POST /api/database/{id}/rescan_values

curl -X POST \
  https://your-metabase.com/api/database/1/rescan_values \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Discard cached field values

Clear cached field values for a database. 
POST /api/database/{id}/discard_values

curl -X POST \
  https://your-metabase.com/api/database/1/discard_values \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Validate database connection

Test database connection details before saving. 
POST /api/database/validate

curl -X POST \
  https://your-metabase.com/api/database/validate \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "engine": "postgres",
    "details": {
      "host": "localhost",
      "port": 5432,
      "dbname": "test",
      "user": "user",
      "password": "pass"
    }
  }'

​
Request body

​
engine
string
required
Database engine type
​
details
object
required
Connection details to validate

​
Response

​
valid
boolean
Whether the connection is valid
​
message
string
Error message if connection failed
{
  "valid": true
}

​
Get autocomplete suggestions

Get SQL autocomplete suggestions for native queries. 
GET /api/database/{id}/autocomplete_suggestions

curl -X GET \
  'https://your-metabase.com/api/database/1/autocomplete_suggestions?query=SELECT%20*%20FROM%20' \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Parameters

​
id
integer
required
Database ID
​
query
string
required
Partial SQL query to get suggestions for

​
Response

Returns an array of autocomplete suggestions including table names, column names, and SQL keywords.

​
Sample database

Create or restore the sample database. 
POST /api/database/sample_database

curl -X POST \
  https://your-metabase.com/api/database/sample_database \
  -H 'X-Metabase-Session: SESSION_TOKEN'
The sample database is useful for testing and demonstrations. It contains sample data across multiple tables.

​
Database healthcheck

Check the health and connectivity of a database. 
GET /api/database/{id}/healthcheck

curl -X GET \
  https://your-metabase.com/api/database/1/healthcheck \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Response

​
status
string
Health status: “ok” or “error”
​
message
string
Error message if health check failed

​
Error codes

Common error codes for database endpoints:
​
400 Bad Request
error
Invalid database configuration or connection details
​
403 Forbidden
error
Insufficient permissions to manage databases (requires admin)
​
404 Not Found
error
Database not found
​
500 Internal Server Error
error
Database connection or sync error