API Reference

Databases API

Programmatically manage your monitored database connections. Add new databases, configure audit settings, and monitor connection health through the REST API.

Base URL

https://api.dbaudit.ai/v1

Supported Databases

DB Audit supports monitoring for all major database platforms. Each database type has specific configuration options and audit capabilities.

PostgreSQL

11, 12, 13, 14, 15, 16

MySQL

5.7, 8.0, 8.4

SQL Server

2016, 2019, 2022

Oracle

12c, 18c, 19c, 21c, 23ai

MongoDB

5.0, 6.0, 7.0, 8.0

MariaDB

10.5, 10.6, 10.11, 11.x

Endpoints

Method	Endpoint	Description	Scope
GET	`/v1/databases`	List all monitored database connections	`read:databases`
POST	`/v1/databases`	Add a new database connection for monitoring	`write:databases`
GET	`/v1/databases/{id}`	Get details of a specific database connection	`read:databases`
PATCH	`/v1/databases/{id}`	Update database connection settings	`write:databases`
DELETE	`/v1/databases/{id}`	Remove a database connection from monitoring	`write:databases`
GET	`/v1/databases/{id}/status`	Get real-time connection and audit status	`read:databases`
POST	`/v1/databases/{id}/test`	Test database connection credentials	`write:databases`

GET /v1/databases

List Databases

Retrieve a paginated list of all database connections in your account. Supports filtering by status, type, and tags.

Query Parameters

status Filter by connection status (connected, disconnected, pending, error)

type Filter by database type (postgresql, mysql, sqlserver, oracle, mongodb)

tags Filter by tags (comma-separated)

page Page number (default: 1)

per_page Results per page (default: 20, max: 100)

# List all monitored databases
curl -X GET "https://api.dbaudit.ai/v1/databases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Response
{
  "data": [
    {
      "id": "db_abc123",
      "name": "Production PostgreSQL",
      "type": "postgresql",
      "host": "prod-db.example.com",
      "port": 5432,
      "status": "connected",
      "audit_status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "last_event_at": "2024-01-20T14:22:15Z"
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "per_page": 20
  }
}

POST /v1/databases

Create Database Connection

Add a new database connection to your monitoring environment. The connection will be tested and validated before being activated.

Request Body

name required Human-readable name for the database

type required Database type (postgresql, mysql, sqlserver, oracle, mongodb, mariadb)

host required Database server hostname or IP address

port required Database server port number

database required Name of the database to monitor

username required Username for database connection

password required Password for database connection (stored encrypted)

ssl_mode optional SSL connection mode (disable, require, verify-ca, verify-full)

tags optional Array of tags for organization

audit_options optional Audit configuration object

# Add a new database connection
curl -X POST "https://api.dbaudit.ai/v1/databases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production PostgreSQL",
    "type": "postgresql",
    "host": "prod-db.example.com",
    "port": 5432,
    "database": "myapp",
    "username": "dbaudit_reader",
    "password": "secure_password",
    "ssl_mode": "verify-full",
    "ssl_ca": "-----BEGIN CERTIFICATE-----...",
    "tags": ["production", "critical"],
    "audit_options": {
      "capture_queries": true,
      "capture_results": false,
      "mask_sensitive_data": true
    }
  }'

# Response
{
  "id": "db_xyz789",
  "name": "Production PostgreSQL",
  "type": "postgresql",
  "status": "pending",
  "created_at": "2024-01-20T15:00:00Z"
}

Credential Security

Database credentials are encrypted at rest using AES-256 and never logged. For enhanced security, consider using IAM authentication or certificate-based auth where supported.

GET /v1/databases/{id}

Get Database Details

Retrieve detailed information about a specific database connection, including statistics, health metrics, and configuration.

# Get database details
curl -X GET "https://api.dbaudit.ai/v1/databases/db_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "id": "db_abc123",
  "name": "Production PostgreSQL",
  "type": "postgresql",
  "host": "prod-db.example.com",
  "port": 5432,
  "database": "myapp",
  "username": "dbaudit_reader",
  "ssl_mode": "verify-full",
  "status": "connected",
  "audit_status": "active",
  "stats": {
    "events_today": 15420,
    "events_this_week": 98540,
    "alerts_pending": 3,
    "policies_active": 8
  },
  "health": {
    "latency_ms": 12,
    "last_heartbeat": "2024-01-20T15:30:00Z"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T12:00:00Z"
}

PATCH /v1/databases/{id}

Update Database

Update the configuration of an existing database connection. Only include fields you want to change.

# Update database settings
curl -X PATCH "https://api.dbaudit.ai/v1/databases/db_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production PostgreSQL (Primary)",
    "tags": ["production", "critical", "pci-dss"],
    "audit_options": {
      "capture_queries": true,
      "capture_results": true,
      "mask_sensitive_data": true,
      "retention_days": 90
    }
  }'

DELETE /v1/databases/{id}

Delete Database

Remove a database connection from monitoring. This action does not delete historical audit data, which is retained according to your retention policy.

# Remove a database from monitoring
curl -X DELETE "https://api.dbaudit.ai/v1/databases/db_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response: 204 No Content

Caution

Deleting a database stops all monitoring and alerting. Active policies will be deactivated. This action cannot be undone.

GET /v1/databases/{id}/status

Get Database Status

Retrieve real-time status information including connection health, collector metrics, and the most recent audit event.

# Get real-time database status
curl -X GET "https://api.dbaudit.ai/v1/databases/db_abc123/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "id": "db_abc123",
  "connection_status": "connected",
  "audit_status": "active",
  "collector": {
    "version": "2.4.1",
    "uptime_seconds": 864000,
    "events_per_second": 42.5
  },
  "health_checks": {
    "connectivity": "healthy",
    "permissions": "healthy",
    "latency": "healthy",
    "disk_space": "warning"
  },
  "last_event": {
    "timestamp": "2024-01-20T15:30:45Z",
    "type": "query",
    "user": "app_user"
  }
}

POST /v1/databases/{id}/test

Test Connection

Test the database connection and verify that the configured credentials have the required permissions for auditing.

# Test database connection
curl -X POST "https://api.dbaudit.ai/v1/databases/db_abc123/test" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "success": true,
  "latency_ms": 15,
  "version": "PostgreSQL 16.1",
  "permissions": {
    "select": true,
    "pg_read_all_stats": true,
    "pg_monitor": true
  },
  "warnings": []
}

Database Object Schema

The database object contains the following fields:

Field	Type	Description
`id`	`string`	Unique identifier for the database connection
`name`	`string`	Human-readable name for the database
`type`	`string`	Database type (postgresql, mysql, sqlserver, oracle, mongodb, mariadb)
`host`	`string`	Database server hostname or IP address
`port`	`integer`	Database server port number
`database`	`string`	Name of the database to monitor
`username`	`string`	Username for database connection
`ssl_mode`	`string`	SSL/TLS connection mode
`status`	`string`	Connection status (connected, disconnected, pending, error)
`audit_status`	`string`	Audit status (active, paused, initializing)
`tags`	`array`	Custom tags for organization and filtering
`created_at`	`datetime`	Timestamp when the connection was created
`updated_at`	`datetime`	Timestamp of last update

SDK Examples

Use our official SDKs for simplified database management in your preferred language.

Python

import dbaudit

client = dbaudit.Client()

# List all databases
databases = client.databases.list()
for db in databases:
    print(f"{db.name}: {db.status}")

# Add a new database
new_db = client.databases.create(
    name="Production PostgreSQL",
    type="postgresql",
    host="prod-db.example.com",
    port=5432,
    database="myapp",
    username="dbaudit_reader",
    password="secure_password",
    ssl_mode="verify-full"
)

# Get database status
status = client.databases.get_status("db_abc123")
print(f"Events per second: {status.collector.events_per_second}")

Node.js

import { DBaudit } from '@dbaudit/sdk';

const client = new DBaudit();

// List all databases
const databases = await client.databases.list();
databases.forEach(db => {
  console.log(`${db.name}: ${db.status}`);
});

// Add a new database
const newDb = await client.databases.create({
  name: 'Production PostgreSQL',
  type: 'postgresql',
  host: 'prod-db.example.com',
  port: 5432,
  database: 'myapp',
  username: 'dbaudit_reader',
  password: 'secure_password',
  sslMode: 'verify-full',
});

// Get database status
const status = await client.databases.getStatus('db_abc123');
console.log(`Events per second: ${status.collector.eventsPerSecond}`);

Error Responses

Common error responses for the Databases API:

400

Bad Request

Invalid request body or missing required fields.

404

Not Found

Database connection with the specified ID does not exist.

409

Conflict

A database with the same host/port/database combination already exists.

422

Unprocessable Entity

Connection test failed. Check credentials and network connectivity.

Related Resources

Explore more API endpoints and database-specific documentation:

Policies API

Events API

PostgreSQL Connector Guide

Start Monitoring Your Databases

Add your first database connection and start receiving security insights within minutes.

Create Free Account Quickstart Guide