Servers
Register, list, update, and decommission MySQL servers
Manage the MySQL servers tracked by dbtrail. All endpoints require authentication and the servers:read, servers:write, or servers:delete permission.
Endpoints
| Method | Endpoint | Permission | Description |
|---|---|---|---|
GET | /servers | servers:read | List all registered servers |
GET | /servers/{server_id} | servers:read | Get server details |
POST | /servers | servers:write | Register a new server |
PATCH | /servers/{server_id} | servers:write | Update server configuration |
DELETE | /servers/{server_id} | servers:delete | Decommission a server (soft-delete) |
GET | /servers/{server_id}/onboarding-status | servers:read | Get onboarding step progress |
POST | /servers/{server_id}/confirm-firewall | servers:write | Confirm firewall whitelist (SSH tunnel servers) |
GET /servers/{server_id}/onboarding-status
Returns step-level progress for a server's onboarding flow. Poll this endpoint while the server is in a non-terminal status.
Response fields:
| Field | Type | Description |
|---|---|---|
server_id | string | Server UUID |
current_step | string | null | The step currently being executed |
steps | array | Ordered list of onboarding steps with status and timing |
error | string | null | Error message from the first failed step, if any |
agent_outbound_ip | string | null | The IP to whitelist — only present when current_step is awaiting_firewall |
Onboarding steps (in order):
| Step | Description |
|---|---|
provisioning | Assigning compute resources |
awaiting_firewall | Waiting for customer to whitelist our outbound IP (SSH tunnel only; auto-completed for direct/VPN) |
waiting_for_agent | Agent is starting up |
initializing | Creating index tables |
snapshotting | Capturing current schema structure |
streaming | Starting binlog stream |
POST /servers/{server_id}/confirm-firewall
Confirms that the customer has whitelisted dbtrail's outbound IP on their SSH jumphost security group. This completes the awaiting_firewall onboarding step and resumes the remaining onboarding steps in the background.
Preconditions (returns 400 if not met):
- Server must use
connection_method: "ssh_tunnel" - Server must be at
onboarding_step: "awaiting_firewall"
Response:
{ "status": "confirmed" }