Connection API Reference

This guide provides a complete reference for the DBConvert Streams Connection API endpoints. For practical implementation examples in different programming languages (curl, Python, Node.js, PowerShell), see our Programming Examples Guide.

Prerequisites

• A valid DBConvert Streams API key
• The API server running (default: http://127.0.0.1:8020/api/v1)
• Basic understanding of REST APIs and JSON

Important

Before using any connection or stream endpoints, you must first call the /user/configs endpoint to load existing configurations:

curl -X GET "http://127.0.0.1:8020/api/v1/user/configs" \
  -H "X-API-Key: your_api_key_here"

This endpoint loads all user configurations including existing connections and stream configurations. Make sure to call this endpoint:

• When starting your application
• Before listing or managing connections
• Before creating or managing streams

API Endpoints Overview

Endpoint	Method	Description
/connections	GET	List all connections
/connections	POST	Create a new connection
/connections/{id}	GET	Get connection details
/connections/{id}	PUT	Update a connection
/connections/{id}	DELETE	Delete a connection
/connections/{id}/ping	POST	Test a connection
/connections/{id}/clone	PUT	Clone a connection
/connections/{id}/databases	GET	List available databases
/connections/{id}/schemas	POST	Create a new schema (PostgreSQL only)
/connections/{id}/tables	GET	List tables in database

Authentication

All API requests require authentication using your API key. Include it in the request header:

X-API-Key: your_api_key_here

Endpoint Details

Create Connection

POST /connections

Creates a new database connection.

Required Fields

• name: A unique name for your connection
• type: Database type (mysql or postgresql)
• host: Database server hostname or IP
• port: Database server port
• username: Database user
• password: Database password
• database: Database name

Optional Fields

• schema: Database schema (PostgreSQL only)

Response

{
  "id": "conn_2sZyDMeIbdaXnN9OL7vYzzAiZU5",
  "name": "mysql-source",
  "type": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "database": "source_db"
}

Test Connection

POST /connections/{connection_id}/ping

Tests if a connection is working properly.

Response - Success

{
  "ping": "ok"
}

Response - Failure

{
  "ping": "failed",
  "error": "Connection refused"
}

List Connections

GET /connections

Returns an array of all configured connections.

Response

[
  {
    "id": "conn_2sZyDMeIbdaXnN9OL7vYzzAiZU5",
    "name": "mysql-source",
    "type": "mysql",
    "host": "localhost",
    "port": 3306
  }
]

Get Connection Details

GET /connections/{connection_id}

Returns detailed information about a specific connection.

Update Connection

PUT /connections/{connection_id}

Updates an existing connection. Requires all fields to be provided, even if only some are being changed.

Delete Connection

DELETE /connections/{connection_id}

Removes a connection. Returns 204 on success.

Clone Connection

PUT /connections/{connection_id}/clone

Creates a copy of an existing connection with a new ID.

Response

{
  "id": "conn_2sZyDMeIbdaXnN9OL7vYzzAiZU5",
  "created": 1738677334
}

List Databases

GET /connections/{connection_id}/databases

Lists all available databases for a connection.

Response (MySQL)

[
  {
    "name": "source_db"
  },
  {
    "name": "new_db"
  }
]

Response (PostgreSQL)

[
  {
    "name": "postgres",
    "schemas": ["public", "custom_schema"]
  }
]

Create Schema

POST /connections/{connection_id}/schemas?database=database_name

Creates a new schema in a PostgreSQL database.

Request Body

"new_schema_name"

List Tables

GET /connections/{connection_id}/tables

Lists all tables in the configured database.

Response

[
  "users",
  "products",
  "orders"
]

Error Handling

The API uses standard HTTP status codes and returns error details in the response body:

{
  "error": "Error message description"
}

Common status codes:

• 400: Invalid request
• 401: Invalid or missing API key
• 404: Resource not found
• 503: Service unavailable (e.g., failed connection test)

See Also

• Connection API Examples - Programming examples in various languages
• Stream API Reference - API reference for stream operations
• API Reference Overview - Complete API reference for all endpoints