Connections API Workflows

Use this page when you need to manage connections to databases and storage systems through the API.

A connection defines how DBConvert Streams reaches a data source or target — a database server, cloud storage bucket, or local file system. Most other API operations (streams, Data Explorer, queries) require at least one connection.

For programming examples in curl, Python, Node.js, and PowerShell, see Connection API Examples.

Connection types

Each connection uses a single spec variant matching its type.

Authentication

All connection endpoints require authentication:

-H "X-API-Key: $API_KEY" \
-H "X-Install-ID: $INSTALL_ID"

In desktop mode on localhost, IDE routes can work without an API key.

Endpoints overview

Create a connection

POST /connections

Database connection (MySQL / PostgreSQL)

curl -X POST "$API_URL/connections" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mysql-source",
    "type": "mysql",
    "spec": {
      "database": {
        "host": "localhost",
        "port": 3306,
        "username": "root",
        "password": "secret",
        "database": "source_db"
      }
    }
  }'

Snowflake connection

curl -X POST "$API_URL/connections" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "snowflake-dwh",
    "type": "snowflake",
    "spec": {
      "snowflake": {
        "account": "xy12345.us-east-1",
        "username": "admin",
        "password": "secret",
        "database": "analytics",
        "warehouse": "compute_wh"
      }
    }
  }'

S3 connection

curl -X POST "$API_URL/connections" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "s3-data-lake",
    "type": "s3",
    "spec": {
      "s3": {
        "region": "us-east-1",
        "credentials": {
          "accessKey": "AKIA...",
          "secretKey": "..."
        }
      }
    }
  }'

Response

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

Optional: SSL

Database connections can include SSL configuration:

{
  "ssl": {
    "mode": "require",
    "ca": "-----BEGIN CERTIFICATE-----...",
    "client_cert": "-----BEGIN CERTIFICATE-----...",
    "client_key": "-----BEGIN RSA PRIVATE KEY-----..."
  }
}

SSL modes: disabled, require, verify-ca, verify-full. See SSL Configuration for details.

Optional: SSH tunnel

Database connections can include SSH tunnel configuration:

{
  "ssh": {
    "enabled": true,
    "host": "bastion.example.com",
    "port": 22,
    "user": "tunnel",
    "authMethod": "key",
    "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----..."
  }
}

SSH auth methods: password, key, key-pass.

Test a connection

Before saving

POST /connections/test

Send the full connection body (same as create) to test connectivity without persisting.

After saving

POST /connections/{id}/ping

curl -X POST "$API_URL/connections/$CONN_ID/ping" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID"

Response on success:

{
  "ping": "ok"
}

Response on failure (HTTP 503):

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

List connections

GET /connections

Returns a wrapped response with connection summaries. Supports optional search query parameter.

curl "$API_URL/connections" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID"

Response:

{
  "items": [
    {
      "id": "conn_2sZyDMeIbdaXnN9OL7vYzzAiZU5",
      "name": "mysql-source",
      "type": "mysql",
      "spec": {
        "database": {
          "host": "localhost",
          "port": 3306,
          "username": "root",
          "password": "secret",
          "database": "source_db"
        }
      },
      "created": 1738677334
    }
  ],
  "total": 5,
  "filtered": 5
}

Connection summaries include the full spec (including credentials). SSH and SSL configuration are omitted from the summary.

Get connection details

GET /connections/{id}

Returns the full connection object including spec details.

Update a connection

PUT /connections/{id}

Send the full connection body. Returns 204 on success.

Delete a connection

DELETE /connections/{id}

Requires the X-Confirm-Delete: true header to prevent accidental deletion. Returns 204 on success.

curl -X DELETE "$API_URL/connections/$CONN_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID" \
  -H "X-Confirm-Delete: true"

Delete all connections

DELETE /connections

Requires the X-Confirm-Delete: true header. Returns 204 on success.

Clone a connection

PUT /connections/{id}/clone

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

Response:

{
  "id": "conn_3tAzENfJdceYoO0PM8wZaabjAV6",
  "created": 1738677400
}

List databases

GET /connections/{id}/databases

Returns databases for a connection, with system database detection.

curl "$API_URL/connections/$CONN_ID/databases" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID"

Response for MySQL:

[
  {
    "name": "sakila",
    "isSystem": false
  },
  {
    "name": "information_schema",
    "isSystem": true,
    "systemReason": "readonly_catalog"
  },
  {
    "name": "mysql",
    "isSystem": true,
    "systemReason": "system_grants"
  }
]

Response for PostgreSQL (includes schemas per database):

[
  {
    "name": "postgres",
    "isSystem": false,
    "schemas": [
      {
        "name": "public",
        "isSystem": false
      },
      {
        "name": "pg_catalog",
        "isSystem": true,
        "systemReason": "system_catalog"
      },
      {
        "name": "information_schema",
        "isSystem": true,
        "systemReason": "sql_standard"
      }
    ]
  },
  {
    "name": "template1",
    "isSystem": true,
    "systemReason": "template_database"
  }
]

Create a database

POST /connections/{id}/databases

Creates a new database on the connected server.

List schemas

GET /connections/{id}/databases/{database}/schemas

Returns schema names for a specific database as a string array. Available for PostgreSQL and Snowflake.

["public", "custom_schema"]

Create a schema

POST /connections/{id}/databases/{database}/schemas

Creates a new schema. Available for PostgreSQL and Snowflake.

Request body is a plain JSON string:

"new_schema_name"

List tables

GET /connections/{id}/databases/{database}/tables

Returns table names as a string array. For PostgreSQL, names are schema-qualified.

Query parameters

Example:

curl "$API_URL/connections/$CONN_ID/databases/mydb/tables?schemas=public&include_system=false" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Install-ID: $INSTALL_ID"

Response:

["public.users", "public.orders", "public.products"]

Error handling

The API returns structured errors with classification:

{
  "error": "Validation failed for field 'X-Confirm-Delete': Deletion requires X-Confirm-Delete: true header",
  "type": "validation",
  "code": "VALIDATION_FAILED",
  "details": {
    "field": "X-Confirm-Delete",
    "reason": "Deletion requires X-Confirm-Delete: true header",
    "value": null
  }
}

Common status codes:

Related docs

• Connection API Examples — Programming examples in various languages
• Streams API — Stream operations API
• API Reference — Complete API reference