API Reference Overview

BunnyDB provides a RESTful HTTP API for managing PostgreSQL-to-PostgreSQL CDC replication. This API is the primary interface for creating and controlling replication mirrors, managing database peers, and monitoring replication status.

Base URL

The API runs on port 8112 by default:

http://localhost:8112

All API endpoints are versioned under the /v1 prefix.

Authentication

Most endpoints require authentication using a Bearer token. Obtain a token by logging in via the /v1/auth/login endpoint.

Include the token in the Authorization header:

Authorization: Bearer <your-token>

Permission Levels

BunnyDB has three permission levels for API endpoints:

Administrative operations like creating mirrors, managing users, and modifying peers require admin privileges.

Response Format

All API responses return JSON with the following characteristics:

Success Responses

Successful responses return the requested data with HTTP status codes in the 2xx range:

{
  "id": 1,
  "username": "admin",
  "role": "admin"
}

Error Responses

Errors return a JSON object with an error field and an appropriate HTTP status code:

{
  "error": "Invalid credentials"
}

Common HTTP status codes:

Rate Limiting

BunnyDB does not implement rate limiting as it is designed as an internal tool for managing database replication within trusted networks.

API Endpoints

The BunnyDB API is organized into the following categories:

• Authentication - Login, token management, password changes
• Users - User management (admin only)
• Peers - Database peer configuration and testing
• Mirrors - Mirror creation, status, and deletion
• Mirror Control - Pause, resume, resync, retry operations
• Logs - Query mirror logs with filtering
• Health - Health check endpoint for monitoring

Common Patterns

Creating Resources

Resource creation endpoints use POST requests with JSON payloads:

curl -X POST http://localhost:8112/v1/peers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "source-db",
    "host": "postgres.example.com",
    "port": 5432,
    "user": "replication_user",
    "password": "secret",
    "database": "production",
    "ssl_mode": "require"
  }'

Retrieving Resources

Use GET requests to retrieve resources. List endpoints return arrays:

curl http://localhost:8112/v1/peers \
  -H "Authorization: Bearer <token>"

Single resource endpoints return the object directly:

curl http://localhost:8112/v1/peers/source-db \
  -H "Authorization: Bearer <token>"

Updating Resources

Update endpoints use PUT requests:

curl -X PUT http://localhost:8112/v1/peers/source-db \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "postgres-new.example.com"
  }'

Deleting Resources

Delete endpoints use DELETE requests:

curl -X DELETE http://localhost:8112/v1/peers/source-db \
  -H "Authorization: Bearer <token>"

Control Operations

Mirror control operations use POST requests to action endpoints:

curl -X POST http://localhost:8112/v1/mirrors/my-mirror/pause \
  -H "Authorization: Bearer <token>"

Getting Started

1. Start by authenticating to obtain a Bearer token
2. Create database peers for your source and destination databases
3. Create a replication mirror to begin CDC
4. Use mirror control endpoints to manage the replication
5. Monitor progress with logs and status endpoints