API Reference

The AI DBA Workbench server provides a RESTful API for client applications. This page provides interactive documentation for exploring and testing the API.

API Discovery

The API implements RFC 8631 for API discovery. All JSON responses include a Link header pointing to the OpenAPI specification:

Link: </api/v1/openapi.json>; rel="service-desc"

This enables API discovery tools like restish to automatically understand the API structure.

OpenAPI Specification

The OpenAPI 3.0.3 specification is available at the following locations:

• At runtime via GET /api/v1/openapi.json.
• As a static file at docs/admin-guide/api/openapi.json.

You can use this specification with tools like Postman, Insomnia, or any OpenAPI-compatible client.

API Versioning

All REST API endpoints use version prefixes:

• The current version is /api/v1/.
• The MCP protocol uses /mcp/v1 with separate versioning.

Version changes follow semantic versioning principles. Breaking changes result in a new major version.

Authentication

Most API endpoints require authentication. Include a Bearer token in the Authorization header.

In the following example, the curl command uses a Bearer token to authenticate:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://localhost:8080/api/v1/connections

Tokens can be one of two types:

• Session tokens are obtained via /api/v1/auth/login.
• Service tokens are created via the server command line for programmatic access.

For detailed authentication information, see Managing Users and Permissions.

Interactive API Browser

The interactive API browser renders the OpenAPI specification in a searchable, navigable format.

Open the API Browser

Endpoint Summary

The API provides endpoints in the following categories.

Authentication

Connections

Clusters and Groups

Alerts

Alert Rules

Alert Overrides

Blackouts

Notification Channels

Channel Overrides

Probe Configuration

Probe Overrides

Server Information

Metrics

Timeline

The endpoint takes absolute start_time and end_time values as RFC 3339 timestamps, and validates them with the same rules as a custom window on /api/v1/metrics/query, described under Metric Time Windows below: the end must fall strictly after the start, the start must fall before the present moment, the span must not exceed 366 days, and an end in the future is clamped to the present moment.

Overview

Conversations

LLM Proxy

Memory

MCP Tools

RBAC Management

Utilities

Metric Time Windows

The /api/v1/metrics/query endpoint accepts either a rolling preset or an explicit window. The time_range parameter takes one of the 1h, 6h, 24h, 7d, and 30d presets, or the value custom; the following parameters select the window:

A preset selects a rolling window that ends at the present moment; the server ignores time_start and time_end for every preset. The custom value selects the window between the two supplied timestamps instead.

The server validates a custom window against the following rules, and returns status 400 with an explanatory message when a request breaks one:

• The request must supply both time_start and time_end.
• Both timestamps must parse as RFC 3339 values.
• The end must fall strictly after the start.
• The start must fall before the present moment.
• The span must not exceed 366 days.

The server clamps an end time in the future to the present moment rather than rejecting the request, because a picker set to the current day often overshoots by a few minutes. The span limit protects the server because the bucket width derives from the span; an unbounded window would let a single request scan an arbitrary amount of history.

In the following example, the curl command queries CPU metrics for an eight-hour window in the past:

QUERY="probe_name=pg_sys_cpu_info&connection_id=1"
WINDOW="time_range=custom&time_start=2026-07-01T09:00:00Z"
WINDOW="$WINDOW&time_end=2026-07-01T17:00:00Z"

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://localhost:8080/api/v1/metrics/query?$QUERY&$WINDOW"

The /api/v1/metrics/query, /api/v1/metrics/connection-groups, /api/v1/metrics/performance-summary and /api/v1/metrics/query-stats endpoints support a custom window with the same three parameters and the same rules; performance-summary derives its bucket width from the resolved window, one sixtieth of the span with a ten second floor. The /api/v1/metrics/database-summaries endpoint accepts the presets alone, and /api/v1/metrics/top-queries has no time dimension; that endpoint always reports the latest collected sample.

Error Responses

All API errors return a consistent JSON format.

In the following example, the server returns an error response:

{
  "error": "Description of the error"
}

The following table lists common HTTP status codes: