Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt

Use this file to discover all available pages before exploring further.

​
DB Proxy Routes

DB proxy routes are wire-protocol tunnels that let agents connect to a migrated database through KnoxCall using a localhost:<port> listener. They are created after a migration item has been committed and are removed when the migration is cancelled. All three DB proxy route endpoints require migration_reviewer permission + 5-minute step-up for write operations.

​
POST /admin/migrations/:id/db-proxy-routes

Create a new wire-protocol proxy route for a migration. Auth: migration_reviewer + 5-minute step-up

​
Request body

FieldRequiredDescription
protocol✅Wire protocol: postgres, mysql, mongodb, redis
upstream_host✅Hostname or IP of the real database
upstream_port✅Port of the real database
committed_secret_id✅ID of the committed KnoxCall secret holding the database credentials
local_port✅Agent-local port the tunnel listens on (must be unique per agent)
upstream_database—Database name to connect to
upstream_username—Database username
tls_mode—prefer (default), require, disable
agent_id—Scope the tunnel to a specific agent UUID; omit for any agent
allowed_uids—Array of Unix UIDs allowed to use the tunnel
secret_migration_item_id—Associate the route with a specific migration item
Returns 409 if local_port is already in use for the same agent.

​
Response

{ "id": "route-uuid" }
Status 201 Created.

​
GET /admin/migrations/:id/db-proxy-routes

List all proxy routes for a migration.

​
Response

{
  "routes": [
    {
      "id": "route-uuid",
      "protocol": "postgres",
      "upstream_host": "prod-db.internal",
      "upstream_port": 5432,
      "upstream_database": "myapp",
      "upstream_username": "readonly",
      "tls_mode": "prefer",
      "local_port": 15432,
      "agent_id": null,
      "allowed_uids": [],
      "committed_secret_id": "secret-uuid",
      "secret_migration_item_id": "item-uuid",
      "enabled": true,
      "created_at": "2026-05-25T10:00:00Z",
      "updated_at": "2026-05-25T10:00:00Z"
    }
  ]
}

​
DELETE /admin/migrations/:id/db-proxy-routes/:routeId

Remove a proxy route. The agent tunnel is torn down immediately. Auth: migration_reviewer + 5-minute step-up

​
Response

{ "id": "route-uuid", "deleted": true }
Returns 404 if the route is not found for this migration and tenant.