> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Datasource
> Create a new datasource connection to your data infrastructure. Supports multiple database types and cloud services.
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 /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:
1. In **Settings** page, navigate to the **Service Tokens** section.
2. Click the **"Generate Token"** button to create a new service token if you don't have one already.
```bash Authentication theme={"dark"}
curl --request POST \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_...' \
--header 'Content-Type: application/json'
```
## Headers
Bearer token for API authentication. Use your service token.
```
Authorization: Bearer dbn_live_abc123...
```
Must be set to `application/json` for all requests.
```
Content-Type: application/json
```
## Request Body
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
The datasource type determines which credential fields are required. Each datasource type has specific connection requirements documented in the credentials section.
Connection credentials for the datasource. The structure varies by datasource type, but all types require a `name` field.
All datasource types require:
* `name` (string, required) - Unique name for the datasource within your organization
Unique name for the datasource. This name will be used to reference the datasource in other APIs and configurations.
* Use descriptive names (e.g., "production-postgres", "analytics-snowflake")
* Must be unique within your organization
* Alphanumeric characters, hyphens, and underscores recommended
* Case-sensitive
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.
* **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
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.
Data type of the client identifier column. Must be either `NUMBER` or `STRING`.
**Required when** `tenancyLevel` is `TABLE`.
Schema name where the client mapping table is located.
**Required when** `tenancyLevel` is `TABLE`.
Name of the table that contains client mapping information.
**Required when** `tenancyLevel` is `TABLE`.
Column name in the mapping table that stores the client identifier.
**Required when** `tenancyLevel` is `TABLE`.
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:
Datasource-specific credential fields. The required fields depend on the `datasourceType`.
Snowflake account hostname (e.g., `your-account.snowflakecomputing.com`)
Snowflake username
Snowflake role to use
Snowflake warehouse name
Snowflake database name
Snowflake schema name
Authentication method: `"username/password"` or `"Key-pair authentication"`
Password (required if credentials is `"username/password"`)
Private key (required if credentials is `"Key-pair authentication"`)
Passphrase for the private key (optional)
Database hostname or IP address
Database port number (1-65535)
Database username
Database password
Database name
Schema name
Enable SSL mode (optional)
SSH tunnel setting: `"enable"` or `"disable"` (optional)
SSH server hostname (required if sshTunnel is `"enable"`)
SSH server port (required if sshTunnel is `"enable"`)
SSH username (required if sshTunnel is `"enable"`)
SSH private key (required if sshTunnel is `"enable"`)
CockroachDB hostname or IP address
Database port number (1-65535)
Database username
Database password
Database name
Schema name
Enable SSL mode (optional)
SSH tunnel setting: `"enable"` or `"disable"` (optional)
SSH server hostname (required if sshTunnel is `"enable"`)
SSH server port (required if sshTunnel is `"enable"`)
SSH username (required if sshTunnel is `"enable"`)
SSH private key (required if sshTunnel is `"enable"`)
JSON string containing Google Cloud service account credentials
Google Cloud project ID
BigQuery dataset location (e.g., `"US"`, `"EU"`)
BigQuery dataset ID (optional)
Database hostname or IP address
Database port number (1-65535)
Database username. Note: Uses `user` not `username` for these datasource types.
Database password
SQL Server hostname or IP address. Note: Uses `server` not `host` for MSSQL.
Database port number (1-65535)
Database username. Note: Uses `user` not `username` for MSSQL.
Database password
Database name (optional)
Disable database selection (optional)
Optional MSSQL read-only routing hint. When `true`, Databrain connects with read-only intent for MSSQL workloads.
Database hostname or IP address
Database port number (1-65535)
Database username
Database password
Database name
Databricks server hostname
Databricks HTTP path
Databricks access token
Server type: `"elastic-cloud"`, `"open-cloud"`, or `"self-managed"`
Cloud ID (required if server\_type is `"elastic-cloud"` or `"open-cloud"`)
Server URL (required if server\_type is `"self-managed"`)
Username (required unless `disableAuth` is `true`)
Password (required unless `disableAuth` is `true`)
Disable authentication (optional, default `false`). Only valid when server\_type is `"self-managed"`.
Ignore certificate verification (optional)
Ignore SSL (optional)
Server type: `"elastic-cloud"`, `"open-cloud"`, or `"self-managed"`
Cloud ID (required if server\_type is `"elastic-cloud"` or `"open-cloud"`)
Server URL (required if server\_type is `"self-managed"`)
Username (required unless `disableAuth` is `true`)
Password (required unless `disableAuth` is `true`)
Disable authentication (optional, default `false`). Only valid when server\_type is `"self-managed"`.
Ignore certificate verification (optional)
Ignore SSL (optional)
Firebolt client ID
Firebolt client secret
Firebolt account name
Database name
Engine name
Schema name (optional)
Athena database name
S3 output bucket for query results
AWS access key ID
AWS region
AWS secret access key
Datasource ID (optional)
Trino hostname or IP address
Database port number (1-65535)
Trino catalog name
Schema name
Username
Password
SSH tunnel setting: `"enable"` or `"disable"` (optional)
SSH host (required if sshTunnel is `"enable"`)
SSH port (required if sshTunnel is `"enable"`)
SSH username (required if sshTunnel is `"enable"`)
SSH private key (required if sshTunnel is `"enable"`)
Name for the CSV datasource
S3 bucket name
Path within the bucket (optional, can be empty string)
AWS region (e.g., `"us-east-1"`)
Table level: `"File"` or `"Folder"` (optional)
AWS access key ID
AWS secret access key
## Response
The name of the created datasource (same as credentials.name).
Error field, null when successful. Not included in successful responses.
## Examples
```bash cURL - PostgreSQL Example theme={"dark"}
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"
}
}'
```
```bash cURL - Snowflake Example theme={"dark"}
curl --request POST \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "snowflake",
"credentials": {
"name": "analytics-snowflake",
"host": "account.snowflakecomputing.com",
"username": "user@example.com",
"role": "ANALYST",
"warehouse": "COMPUTE_WH",
"database": "ANALYTICS",
"schema": "PUBLIC",
"credentials": "username/password",
"password": "securepassword"
}
}'
```
```bash cURL - MSSQL Example theme={"dark"}
curl --request POST \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "mssql",
"credentials": {
"name": "production-mssql",
"server": "sqlserver.example.com",
"port": 1433,
"user": "sqluser",
"password": "securepassword",
"database": "analytics",
"readOnlyIntent": true
}
}'
```
```bash cURL - CockroachDB Example theme={"dark"}
curl --request POST \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "cockroachdb",
"credentials": {
"name": "production-cockroachdb",
"host": "cockroach.example.com",
"port": 26257,
"username": "dbuser",
"password": "securepassword",
"database": "analytics",
"schema": "public"
}
}'
```
```bash cURL - OpenSearch Example theme={"dark"}
curl --request POST \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "opensearch",
"credentials": {
"name": "production-opensearch",
"server_type": "self-managed",
"server_url": "https://opensearch.example.com:9200",
"username": "admin",
"password": "securepassword"
}
}'
```
```bash cURL - Elasticsearch Example theme={"dark"}
curl --request POST \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "elasticsearch",
"credentials": {
"name": "production-elasticsearch",
"server_type": "elastic-cloud",
"cloud_id": "my-deployment:dXMtZWFzdC0xLmF3cy5mb3VuZC5pbyQ...",
"username": "elastic",
"password": "securepassword"
}
}'
```
```bash cURL - Trino Example theme={"dark"}
curl --request POST \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "trino",
"credentials": {
"name": "production-trino",
"host": "trino.example.com",
"port": 8080,
"catalog": "hive",
"schema": "analytics",
"username": "trinouser",
"password": "securepassword"
}
}'
```
```bash cURL - With Tenancy Settings theme={"dark"}
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": "multi-tenant-postgres",
"host": "db.example.com",
"port": 5432,
"username": "dbuser",
"password": "securepassword",
"database": "analytics",
"schema": "public"
},
"tenancySettings": {
"tenancyLevel": "TABLE",
"clientColumnType": "STRING",
"schemaName": "public",
"tableName": "clients",
"tableClientNameColumn": "client_name",
"tablePrimaryKeyColumn": "client_id"
}
}'
```
```javascript Node.js theme={"dark"}
const response = await fetch('https://api.usedatabrain.com/api/v2/datasource', {
method: 'POST',
headers: {
'Authorization': 'Bearer dbn_live_abc123...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
datasourceType: 'postgres',
credentials: {
name: 'production-postgres',
host: 'db.example.com',
port: 5432,
username: 'dbuser',
password: 'securepassword',
database: 'analytics',
schema: 'public'
}
})
});
const data = await response.json();
if (data.error) {
console.error('Error:', data.error);
} else {
console.log('Datasource created:', data.name);
}
```
```python Python theme={"dark"}
import requests
response = requests.post(
'https://api.usedatabrain.com/api/v2/datasource',
headers={
'Authorization': 'Bearer dbn_live_abc123...',
'Content-Type': 'application/json'
},
json={
'datasourceType': 'postgres',
'credentials': {
'name': 'production-postgres',
'host': 'db.example.com',
'port': 5432,
'username': 'dbuser',
'password': 'securepassword',
'database': 'analytics',
'schema': 'public'
}
}
)
data = response.json()
if data.get('error'):
print('Error:', data['error'])
else:
print('Datasource created:', data['name'])
```
```json 200 - Success theme={"dark"}
{
"name": "production-postgres"
}
```
```json 400 - Bad Request theme={"dark"}
{
"error": {
"code": "INVALID_REQUEST_BODY",
"message": "Invalid credentials for postgres: \"host\" is required",
"status": 400
}
}
```
```json 400 - Duplicate Name theme={"dark"}
{
"error": {
"code": "DATASOURCE_NAME_ERROR",
"message": "Datasource name already exists, please use unique name",
"status": 400
}
}
```
```json 400 - Connection Test Failed theme={"dark"}
{
"error": {
"code": "CREDENTIAL_TEST_FAILED",
"message": "Failed to connect to datasource",
"status": 400
}
}
```
```json 401 - Unauthorized theme={"dark"}
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "AUTHENTICATION_ERROR",
"status": 401
}
}
```
## 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
View all datasources in your organization
Update datasource credentials or configuration
Sync datasource schema after creation
Create a datamart using your new datasource