Create Datasource - Databrain

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/datasource \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datasourceType": "postgres",
    "credentials": {
      "name": "production-postgres",
      "host": "db.example.com",
      "port": 5432,
      "username": "dbuser",
      "password": "securepassword",
      "database": "analytics",
      "schema": "public"
    }
  }'

{
  "name": "production-postgres"
}

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/datasource \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datasourceType": "postgres",
    "credentials": {
      "name": "production-postgres",
      "host": "db.example.com",
      "port": 5432,
      "username": "dbuser",
      "password": "securepassword",
      "database": "analytics",
      "schema": "public"
    }
  }'

{
  "name": "production-postgres"
}

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/datasource \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datasourceType": "postgres",
    "credentials": {
      "name": "production-postgres",
      "host": "db.example.com",
      "port": 5432,
      "username": "dbuser",
      "password": "securepassword",
      "database": "analytics",
      "schema": "public"
    }
  }'

{
  "name": "production-postgres"
}

POST

api

datasource

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/datasource \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datasourceType": "postgres",
    "credentials": {
      "name": "production-postgres",
      "host": "db.example.com",
      "port": 5432,
      "username": "dbuser",
      "password": "securepassword",
      "database": "analytics",
      "schema": "public"
    }
  }'

{
  "name": "production-postgres"
}

Create a new datasource connection to integrate your database or data warehouse with DataBrain. The API validates credentials, tests the connection, and automatically caches the schema for immediate use.

Before creating a datasource, ensure you have valid credentials for your database or data warehouse. The API will test the connection before creating the datasource. Supported datasource types include Snowflake, PostgreSQL, MySQL, BigQuery, Databricks, and many more.

Endpoint

POST https://api.usedatabrain.com/api/v2/datasource

Self-hosted Databrain Endpoint

POST <SELF_HOSTED_URL>/api/v2/datasource

Authentication

This endpoint requires a service token in the Authorization header. Service tokens differ from data app API keys and provide organization-level permissions. To access your service token:

In Settings page, navigate to the Service Tokens section.
Click the “Generate Token” button to create a new service token if you don’t have one already.

Headers

Authorization

string

required

Bearer token for API authentication. Use your service token.

Authorization: Bearer dbn_live_abc123...

Content-Type

string

required

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

datasourceType

string

required

The type of datasource to create. Must be one of the supported datasource types.Supported types:

snowflake - Snowflake data warehouse
postgres - PostgreSQL database
redshift - Amazon Redshift
cockroachdb - CockroachDB
mysql - MySQL database
mongodb - MongoDB database
clickhouse - ClickHouse database
singlestore - SingleStore database
bigquery - Google BigQuery
databricks - Databricks
elasticsearch - Elasticsearch
opensearch - OpenSearch
mssql - Microsoft SQL Server
awss3 - Amazon S3
csv - CSV files
firebolt - Firebolt
athena - Amazon Athena
trino - Trino

Show Datasource type details

The datasource type determines which credential fields are required. Each datasource type has specific connection requirements documented in the credentials section.

credentials

object

required

Connection credentials for the datasource. The structure varies by datasource type, but all types require a name field.

Show Common credential fields

All datasource types require:

name (string, required) - Unique name for the datasource within your organization

credentials.name

string

required

Unique name for the datasource. This name will be used to reference the datasource in other APIs and configurations.

Show Naming guidelines

Use descriptive names (e.g., “production-postgres”, “analytics-snowflake”)
Must be unique within your organization
Alphanumeric characters, hyphens, and underscores recommended
Case-sensitive

tenancySettings

object

Multi-tenant configuration for the datasource. Defines how data is isolated between different tenants/clients. Optional - if not provided, the datasource will be created without explicit tenancy settings.

Show Tenancy configuration details

TABLE level: Uses a dedicated table to map client identifiers
DATABASE level: Each client has a separate database
Optional - can be omitted if tenancy is handled at the application level

tenancySettings.tenancyLevel

string

The level at which tenant isolation occurs. Must be one of: TABLE or DATABASE.

TABLE: Client mapping is stored in a specific table (most common)
DATABASE: Each client has a separate database instance

Required when tenancySettings is provided. If tenancySettings is omitted, this field is not needed.

tenancySettings.clientColumnType

string

Data type of the client identifier column. Must be either NUMBER or STRING.Required when tenancyLevel is TABLE.

tenancySettings.schemaName

string

Schema name where the client mapping table is located.Required when tenancyLevel is TABLE.

tenancySettings.tableName

string

Name of the table that contains client mapping information.Required when tenancyLevel is TABLE.

tenancySettings.tableClientNameColumn

string

Column name in the mapping table that stores the client identifier.Required when tenancyLevel is TABLE.

tenancySettings.tablePrimaryKeyColumn

string

Primary key column of the client mapping table.Required when tenancyLevel is TABLE.

Datasource-Specific Credentials

The credentials object structure depends on the datasourceType. Below are examples for common datasource types:

credentials

object

Datasource-specific credential fields. The required fields depend on the datasourceType.

Snowflake

credentials.host

string

required

Snowflake account hostname (e.g., your-account.snowflakecomputing.com)

credentials.username

string

required

Snowflake username

credentials.role

string

required

Snowflake role to use

credentials.warehouse

string

required

Snowflake warehouse name

credentials.database

string

required

Snowflake database name

credentials.schema

string

required

Snowflake schema name

credentials.credentials

string

required

Authentication method: "username/password" or "Key-pair authentication"

credentials.password

string

Password (required if credentials is "username/password")

credentials.privateKey

string

Private key (required if credentials is "Key-pair authentication")

credentials.privateKeyPass

string

Passphrase for the private key (optional)

Postgres / Redshift

credentials.host

string

required

Database hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.username

string

required

Database username

credentials.password

string

required

Database password

credentials.database

string

required

Database name

credentials.schema

string

required

Schema name

credentials.sslMode

boolean

Enable SSL mode (optional)

credentials.sshTunnel

string

SSH tunnel setting: "enable" or "disable" (optional)

credentials.sshHost

string

SSH server hostname (required if sshTunnel is "enable")

credentials.sshPort

number

SSH server port (required if sshTunnel is "enable")

credentials.sshUsername

string

SSH username (required if sshTunnel is "enable")

credentials.sshPrivateKey

string

SSH private key (required if sshTunnel is "enable")

CockroachDB

credentials.host

string

required

CockroachDB hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.username

string

required

Database username

credentials.password

string

required

Database password

credentials.database

string

required

Database name

credentials.schema

string

required

Schema name

credentials.sslMode

boolean

Enable SSL mode (optional)

credentials.sshTunnel

string

SSH tunnel setting: "enable" or "disable" (optional)

credentials.sshHost

string

SSH server hostname (required if sshTunnel is "enable")

credentials.sshPort

number

SSH server port (required if sshTunnel is "enable")

credentials.sshUsername

string

SSH username (required if sshTunnel is "enable")

credentials.sshPrivateKey

string

SSH private key (required if sshTunnel is "enable")

BigQuery

credentials.credentials_json

string

required

JSON string containing Google Cloud service account credentials

credentials.project_id

string

required

Google Cloud project ID

credentials.dataset_location

string

required

BigQuery dataset location (e.g., "US", "EU")

credentials.dataset_id

string

BigQuery dataset ID (optional)

MySQL / MongoDB / ClickHouse

credentials.host

string

required

Database hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.user

string

required

Database username. Note: Uses user not username for these datasource types.

credentials.password

string

required

Database password

MSSQL

credentials.server

string

required

SQL Server hostname or IP address. Note: Uses server not host for MSSQL.

credentials.port

number

required

Database port number (1-65535)

credentials.user

string

required

Database username. Note: Uses user not username for MSSQL.

credentials.password

string

required

Database password

credentials.database

string

Database name (optional)

credentials.isDisableDatabase

boolean

Disable database selection (optional)

credentials.readOnlyIntent

boolean

Optional MSSQL read-only routing hint. When true, Databrain connects with read-only intent for MSSQL workloads.

SingleStore

credentials.host

string

required

Database hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.user

string

required

Database username

credentials.password

string

required

Database password

credentials.database

string

required

Database name

Databricks

credentials.serverHostname

string

required

Databricks server hostname

credentials.httpPath

string

required

Databricks HTTP path

credentials.token

string

required

Databricks access token

Elasticsearch

credentials.server_type

string

required

Server type: "elastic-cloud", "open-cloud", or "self-managed"

credentials.cloud_id

string

Cloud ID (required if server_type is "elastic-cloud" or "open-cloud")

credentials.server_url

string

Server URL (required if server_type is "self-managed")

credentials.username

string

Username (required unless disableAuth is true)

credentials.password

string

Password (required unless disableAuth is true)

credentials.disableAuth

boolean

Disable authentication (optional, default false). Only valid when server_type is "self-managed".

credentials.isIgnoreVerifyCert

boolean

Ignore certificate verification (optional)

credentials.isIgnoreSsl

boolean

Ignore SSL (optional)

OpenSearch

credentials.server_type

string

required

Server type: "elastic-cloud", "open-cloud", or "self-managed"

credentials.cloud_id

string

Cloud ID (required if server_type is "elastic-cloud" or "open-cloud")

credentials.server_url

string

Server URL (required if server_type is "self-managed")

credentials.username

string

Username (required unless disableAuth is true)

credentials.password

string

Password (required unless disableAuth is true)

credentials.disableAuth

boolean

Disable authentication (optional, default false). Only valid when server_type is "self-managed".

credentials.isIgnoreVerifyCert

boolean

Ignore certificate verification (optional)

credentials.isIgnoreSsl

boolean

Ignore SSL (optional)

Firebolt

credentials.client_id

string

required

Firebolt client ID

credentials.client_secret

string

required

Firebolt client secret

credentials.account

string

required

Firebolt account name

credentials.database

string

required

Database name

credentials.engineName

string

required

Engine name

credentials.schema

string

Schema name (optional)

Athena

credentials.database

string

required

Athena database name

credentials.outputBucket

string

required

S3 output bucket for query results

credentials.s3AccessKeyId

string

required

AWS access key ID

credentials.s3Region

string

required

AWS region

credentials.s3SecretAccessKey

string

required

AWS secret access key

credentials.datasourceId

string

Datasource ID (optional)

Trino

credentials.host

string

required

Trino hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.catalog

string

required

Trino catalog name

credentials.schema

string

required

Schema name

credentials.username

string

required

Username

credentials.password

string

required

Password

credentials.sshTunnel

string

SSH tunnel setting: "enable" or "disable" (optional)

credentials.sshHost

string

SSH host (required if sshTunnel is "enable")

credentials.sshPort

number

SSH port (required if sshTunnel is "enable")

credentials.sshUsername

string

SSH username (required if sshTunnel is "enable")

credentials.sshPrivateKey

string

SSH private key (required if sshTunnel is "enable")

CSV

credentials.name

string

required

Name for the CSV datasource

AWS S3

credentials.bucketName

string

required

S3 bucket name

credentials.datasetPath

string

Path within the bucket (optional, can be empty string)

credentials.s3Region

string

required

AWS region (e.g., "us-east-1")

credentials.tableLevel

string

Table level: "File" or "Folder" (optional)

credentials.s3AccessKeyId

string

required

AWS access key ID

credentials.s3SecretAccessKey

string

required

AWS secret access key

Response

name

string

The name of the created datasource (same as credentials.name).

error

null

Error field, null when successful. Not included in successful responses.

Examples

Error Codes

Error Code	HTTP Status	Description
`INVALID_REQUEST_BODY`	400	Missing required fields or invalid credential structure
`DATASOURCE_NAME_ERROR`	400	Datasource name already exists
`CREDENTIAL_TEST_FAILED`	400	Connection test failed
`AUTHENTICATION_ERROR`	401	Invalid or missing service token
`SCHEMA_CACHE_FAILED`	500	Schema caching failed
`CREATE_DATASOURCE_FAILED`	500	Internal error during datasource creation
`INTERNAL_SERVER_ERROR`	500	Server error occurred

Next Steps

List Datasources

View all datasources in your organization

Update Datasource

Update datasource credentials or configuration

Sync Datasource

Sync datasource schema after creation

Create Datamart

Create a datamart using your new datasource

Guest Token

List Datasources

​Endpoint

​Self-hosted Databrain Endpoint

​Authentication

​Headers

​Request Body

​Datasource-Specific Credentials

​Response

​Examples

​Error Codes

​Next Steps

List Datasources

Update Datasource

Sync Datasource

Create Datamart

Endpoint

Self-hosted Databrain Endpoint

Authentication

Headers

Request Body

Datasource-Specific Credentials

Response

Examples

Error Codes

Next Steps