API Reference

All endpoints are under https://api.usebasira.com/api/v1. Authenticate with an API key (X-API-Key header) or JWT token (Authorization: Bearer header). See Authentication for details.

All timestamps are RFC 3339 format. Error responses use {"error": "message"}.

Databases

List Databases

GET /api/v1/databases

Returns all databases in your organization.

Register Database

POST /api/v1/databases

Unverified accounts are limited to 1 database.

Get Database

GET /api/v1/databases/{id}

Update Database

PATCH /api/v1/databases/{id}

Delete Database

DELETE /api/v1/databases/{id}

Returns 204 No Content. Cascades to related alerts and recommendations.

Database Health

GET /api/v1/databases/{id}/health

Response: { "id": "...", "status": "connected|disconnected", "last_seen_at": "..." }

Queries

List Query Statistics

GET /api/v1/databases/{id}/queries

Response fields: query_hash, query_text, total_calls, total_time_ms, mean_time_ms, total_rows, shared_blks_hit, shared_blks_read, cache_hit_ratio.

Get Query Detail

GET /api/v1/databases/{id}/queries/{hash}

Returns query metadata plus timeseries array with per-interval breakdowns of calls, time, rows, and block I/O.

Get EXPLAIN Plans

GET /api/v1/databases/{id}/queries/{hash}/explain

Response fields per plan: ts, plan_json, plan_hash, total_cost, actual_time_ms, seq_scans, index_scans, rows_estimated, rows_actual.

Active Queries & Locks

List Active Queries

GET /api/v1/databases/{id}/active

Response fields: pid, query_text, state, wait_event_type, wait_event, duration_ms, blocking_pids, ts. ClickHouse adds memory_usage, read_bytes, written_bytes, read_rows.

Active Queries WebSocket

GET /api/v1/databases/{id}/active/ws?token={jwt}&interval=5

Streams active query snapshots at the specified interval (seconds). Authenticate via token query param or session cookie.

List Locks

GET /api/v1/databases/{id}/locks

Response fields: pid, lock_type, mode, relation_name, granted, blocked_by_pid, duration_ms, query_text, ts.

Wait Events

GET /api/v1/databases/{id}/waits

Response fields: ts, wait_event_type, wait_event, count, total_duration_ms.

Tables & Indexes

List Tables

GET /api/v1/databases/{id}/tables

Response fields: schema_name, table_name, seq_scan, idx_scan, n_tup_ins, n_tup_upd, n_tup_del, n_live_tup, n_dead_tup, last_vacuum, last_autovacuum, last_analyze, table_size_bytes, index_size_bytes.

Get Table Detail

GET /api/v1/databases/{id}/tables/{schema}/{name}

Returns table metadata plus timeseries array.

List Indexes

GET /api/v1/databases/{id}/indexes

Response fields: schema_name, table_name, index_name, idx_scan, idx_tup_read, idx_tup_fetch, size_bytes, index_def, is_unique, is_primary, is_valid.

Unused Indexes

GET /api/v1/databases/{id}/indexes/unused

Same response as List Indexes, filtered to indexes with 0 scans, not primary, not unique, and over 1 MB.

Get Index Detail

GET /api/v1/databases/{id}/indexes/{schema}/{name}

Returns index metadata plus timeseries array.

Dashboard & Health

Overview

GET /api/v1/databases/{id}/overview

Returns a summary of database health. Response includes engine, status, last_seen_at, health_score (0–100), active_queries, longest_query_ms, and top_queries.

PostgreSQL adds: blocked_queries, cache_hit_ratio, dead_tuple_ratio, last_autovacuum.

ClickHouse adds: active_merges, merge_progress_pct, active_mutations, stuck_mutations, query_p99_ms.

Health Diagnosis

GET /api/v1/databases/{id}/doctor

Returns status (healthy, degraded, unhealthy), score (0–100), top_issues array with severity, category, title, detail, recommendation, how_to_investigate, how_to_fix, and a metrics_summary.

Replication (PostgreSQL)

Current Status

GET /api/v1/databases/{id}/replication

Response: is_replica, replication_lag_bytes, replication_lag_seconds, upstream_host, slots array.

Lag History

GET /api/v1/databases/{id}/replication/history

Slot History

GET /api/v1/databases/{id}/replication/slots/history

Same params as lag history. Response includes slot_name and lag_bytes per interval.

PostgreSQL Internals

Background Writer

GET /api/v1/databases/{id}/bgwriter

Returns timeseries with checkpoint and buffer write statistics.

WAL Statistics

GET /api/v1/databases/{id}/wal-stats

Returns current WAL generation stats (PostgreSQL 14+).

WAL Timeseries

GET /api/v1/databases/{id}/wal-stats/timeseries

Returns WAL stats over time with since, until params.

I/O Statistics

GET /api/v1/databases/{id}/io-stats

Returns current I/O stats by backend/object/context (PostgreSQL 16+).

I/O Timeseries

GET /api/v1/databases/{id}/io-stats/timeseries

Returns I/O stats over time with since, until params.

ClickHouse Internals

Parts

GET /api/v1/databases/{id}/parts

Returns part statistics for MergeTree tables.

Merges

GET /api/v1/databases/{id}/merges

Returns currently active merge operations.

Mutations

GET /api/v1/databases/{id}/mutations

Returns mutation status for ALTER TABLE operations.

Server Metrics

GET /api/v1/databases/{id}/server-metrics

Returns server-level metrics: memory, disk, connections, uptime.

API Keys

List Keys

GET /api/v1/api-keys

Create Key

POST /api/v1/api-keys

Response includes the full key — this is the only time it's shown.

Revoke Key

DELETE /api/v1/api-keys/{id}

Returns 204 No Content.

Account

Current User

GET /api/v1/auth/me

Returns user info (when using JWT) or organization info (when using API key). Includes organization with id, name, slug, plan, verified.

Signup

POST /api/v1/auth/signup

Login

POST /api/v1/auth/login

Response: { "access_token": "...", "refresh_token": "...", "expires_in": 900 }

Refresh Token

POST /api/v1/auth/refresh

Logout

POST /api/v1/auth/logout

Clears session cookies. Returns 204.

Verify Email

GET /api/v1/auth/verify-email?token={token}

Forgot Password

POST /api/v1/auth/forgot-password

Always returns success (does not leak whether the email exists).

Reset Password

POST /api/v1/auth/reset-password

Health Check

GET /healthz

No authentication required. Returns 200 if the API is running.