SQL Connectors¶

Connect and sync data from SQL databases including MySQL, PostgreSQL, SQL Server, Oracle, and MariaDB.

Base URL¶

BASE_URL = "https://api.fermi.dev/public/v1"

All endpoints are relative to this base URL.

Authentication¶

All endpoints require authentication. Use a service actor token:

Authorization: Bearer <service-actor-token>

Required Scopes:

• connectors:read - For read endpoints
• connectors:write - For write endpoints
• connectors:sync - For synchronization endpoints

Supported Databases¶

• MySQL - providerConfigKey: mysql
• PostgreSQL - providerConfigKey: postgresql
• SQL Server - providerConfigKey: mssql
• Oracle - providerConfigKey: oracle
• MariaDB - providerConfigKey: mariadb

Save SQL Connection¶

POST /connect/integrations/connect-session

Save a SQL database connection with credentials and connection details.

providerConfigKey, username, password, and metadata.host are required. An empty body can still create a connection with no host — do not rely on that; send the full payload.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "providerConfigKey": "mysql",
  "username": "dbuser",
  "password": "dbpassword",
  "metadata": {
    "connectionName": "Production MySQL",
    "host": "localhost",
    "port": 3306,
    "database": "mydb",
    "schema": ["public"],
    "description": "Production database connection",
    "useSSL": true,
    "sslMode": "require",
    "status": "active",
    "syncStatus": "never"
  }
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/connect/integrations/connect-session" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "providerConfigKey": "mysql",
    "username": "dbuser",
    "password": "dbpassword",
    "metadata": {
      "connectionName": "Production MySQL",
      "host": "localhost",
      "port": 3306,
      "database": "mydb",
      "useSSL": true,
      "description": "Production database"
    }
  }'

Response:

{
  "success": true,
  "connection": {
    "connection_id": "5c096330-fc54-4144-bfec-6bd344da9586",
    "provider_config_key": "mysql"
  }
}

Test Database Connection¶

POST /database/test-connection

Test a database connection before saving.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "databaseType": "mysql",
  "connection": {
    "host": "localhost",
    "port": 3306,
    "database": "mydb",
    "username": "user",
    "password": "password",
    "useSSL": true,
    "sslMode": "require"
  }
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/database/test-connection" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "databaseType": "mysql",
    "connection": {
      "host": "localhost",
      "port": 3306,
      "database": "mydb",
      "username": "user",
      "password": "password",
      "useSSL": true
    }
  }'

Response:

{
  "success": true,
  "message": "Connection successful!"
}

Update Connection Metadata¶

POST /connect/integrations/connection-metadata

Update database connection metadata (without credentials).

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "connection-123",
  "providerConfigKey": "mysql",
  "metadata": {
    "connectionName": "Production MySQL",
    "host": "localhost",
    "port": 3306,
    "database": "mydb",
    "useSSL": true,
    "sslMode": "require",
    "schema": ["public", "analytics"],
    "status": "active",
    "description": "Production database connection"
  }
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/connect/integrations/connection-metadata" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "connection-123",
    "providerConfigKey": "mysql",
    "metadata": {
      "connectionName": "Production MySQL",
      "host": "localhost",
      "port": 3306,
      "database": "mydb",
      "useSSL": true,
      "description": "Production database"
    }
  }'

Response:

{
  "success": true,
  "message": "Metadata updated successfully"
}

List SQL Connections¶

GET /connect/integrations/connections?providerConfigKey={databaseType}

List all connections for a specific database type.

Headers:

Authorization: Bearer <token>

Query Parameters:

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/connections?providerConfigKey=mysql" \
  --header "Authorization: Bearer <token>"

Response:

{
  "connections": [
    {
      "id": 517,
      "connection_id": "5c096330-fc54-4144-bfec-6bd344da9586",
      "provider_config_key": "mysql",
      "created_at": "2025-01-15T10:30:00Z",
      "metadata": {
        "connectionName": "Production MySQL",
        "host": "localhost",
        "port": 3306,
        "database": "mydb",
        "status": "active",
        "syncStatus": "completed"
      }
    }
  ]
}

Get Connection Details¶

GET /connect/integrations/connection-metadata?connectionId={connectionId}&providerConfigKey={databaseType}

Get detailed connection information. connectionId is required. A missing or unknown id can return 500 wrapping a 404 instead of a clean 404.

Headers:

Authorization: Bearer <token>

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/connection-metadata?connectionId=5c096330-fc54-4144-bfec-6bd344da9586&providerConfigKey=mysql" \
  --header "Authorization: Bearer <token>"

Response:

{
  "metadata": {
    "connectionName": "Production MySQL",
    "host": "localhost",
    "port": 3306,
    "database": "mydb",
    "schema": ["public"],
    "useSSL": true,
    "sslMode": "require",
    "status": "active",
    "syncStatus": "completed",
    "lastSyncedAt": "2025-01-15T12:00:00Z",
    "description": "Production database connection"
  }
}

Start Database Sync¶

POST /sync/enqueue

Start data synchronization for a SQL connection.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerKey": "mysql"
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/sync/enqueue" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
    "providerKey": "mysql"
  }'

Response:

{
  "success": true,
  "syncId": "sync-job-123",
  "message": "Sync job queued successfully"
}

Disconnect Database¶

DELETE /connect/integrations/connection/{connectionId}?integration={databaseType}

Remove a database connection.

Headers:

Authorization: Bearer <token>

Query Parameters:

cURL Example:

curl --request DELETE \
  --url "${BASE_URL}/connect/integrations/connection/5c096330-fc54-4144-bfec-6bd344da9586?integration=mysql" \
  --header "Authorization: Bearer <token>"

Live: this DELETE currently returns 502 on the public path. Do not expect the success JSON below until disconnect is fixed. Remove the connection in the Fermi app if you need it gone.

{
  "success": true,
  "message": "Connection deleted successfully"
}

Connection Configuration¶

SQL connection metadata supports the following fields:

Default Ports¶

Endpoints Summary¶

Schema discovery¶

BASE_URL = "https://app.fermi.dev/api/sql"

These routes are Fermi app session APIs (getUser on app.fermi.dev). A service-actor Bearer token is not enough. For a partner connection check, use POST /public/v1/database/test-connection instead.

Tunnel is required: sourceConfig.tunnel_method.tunnel_method must not be NO_TUNNEL. Without a jumpbox, the API returns 400 (Connection check polling is only available when Jumpbox / SSH Tunnel is enabled.).

sourceType is one of postgresql, mysql, mssql, mariadb, oracle.

Features¶

• Multiple Database Support - Connect to MySQL, PostgreSQL, SQL Server, Oracle, and MariaDB
• Connection Testing - Test connections before saving
• SSL Support - Secure connections with SSL/TLS
• Schema Selection - Choose specific schemas to sync
• Data Synchronization - Sync database tables to knowledge graph
• Connection Management - Create, update, and delete connections

Next Steps¶

• Data Connectors Overview - Return to data connectors overview
• API Reference Overview - Return to API reference index
• Scopes and Permissions - Learn about connector scopes
• Code Examples - Examples (coming soon)