Authentication
Datasource APIs
Embeds
Embedding APIs (Legacy)
Data App APIs
Metric APIs
Copy
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"
}
}'
Copy
{
"name": "production-postgres"
}
Copy
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"
}
}'
Copy
{
"name": "production-postgres"
}
Datasource APIs
Create Datasource
Create a new datasource connection to your data infrastructure. Supports multiple database types and cloud services.
Copy
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"
}
}'
Copy
{
"name": "production-postgres"
}
POST
https://api.usedatabrain.com
/
api
/
v2
/
datasource
Copy
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"
}
}'
Copy
{
"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
Copy
POST https://api.usedatabrain.com/api/v2/datasource
Self-hosted Databrain Endpoint
Copy
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:- Go to your Databrain dashboard and open Settings.
- Navigate to Settings.
- Find the Service Tokens section.
- Click the “Generate Token” button to generate a new service token if you don’t have one already. Use this token as the Bearer value in your Authorization header.
Headers
Bearer token for API authentication. Use your API key from the data app.
Copy
Authorization: Bearer dbn_live_abc123...
Must be set to
application/json for all requests.Copy
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 warehousepostgres- PostgreSQL databaseredshift- Amazon Redshiftcockroachdb- CockroachDBmysql- MySQL databasemongodb- MongoDB databaseclickhouse- ClickHouse databasesinglestore- SingleStore databasebigquery- Google BigQuerydatabricks- Databrickselasticsearch- Elasticsearchopensearch- OpenSearchmssql- Microsoft SQL Serverawss3- Amazon S3csv- CSV filesfirebolt- Fireboltathena- Amazon Athenatrino- Trino
Show Datasource type details
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.
Connection credentials for the datasource. The structure varies by datasource type, but all types require a
name field.Show Common credential fields
Show Common credential fields
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.
Show Naming guidelines
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
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
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
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
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 thedatasourceType. Below are examples for common datasource types:
Datasource-specific credential fields. The required fields depend on the
datasourceType.Snowflake
Snowflake
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)
Postgres / Redshift
Postgres / Redshift
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
CockroachDB
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")BigQuery
BigQuery
JSON string containing Google Cloud service account credentials
Google Cloud project ID
BigQuery dataset location (e.g.,
"US", "EU")BigQuery dataset ID (optional)
MySQL / MongoDB / ClickHouse
MySQL / MongoDB / ClickHouse
MSSQL
MSSQL
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)
SingleStore
SingleStore
Databricks
Databricks
Elasticsearch
Elasticsearch
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)
OpenSearch
OpenSearch
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
Firebolt
Firebolt client ID
Firebolt client secret
Firebolt account name
Database name
Engine name
Schema name (optional)
Athena
Athena
Athena database name
S3 output bucket for query results
AWS access key ID
AWS region
AWS secret access key
Datasource ID (optional)
Trino
Trino
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")CSV
CSV
Name for the CSV datasource
AWS S3
AWS S3
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
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
⌘I