Authentication
Datasource APIs
Embeds
Embedding APIs (Legacy)
Data App APIs
Metric APIs
Copy
curl --request PUT \
--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": "new-db.example.com",
"port": 5432,
"username": "dbuser",
"password": "newpassword",
"database": "analytics",
"schema": "public"
}
}'
Copy
{
"name": "production-postgres"
}
Copy
curl --request PUT \
--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": "new-db.example.com",
"port": 5432,
"username": "dbuser",
"password": "newpassword",
"database": "analytics",
"schema": "public"
}
}'
Copy
{
"name": "production-postgres"
}
Datasource APIs
Update Datasource
Update the credentials and configuration of an existing datasource. The API validates and tests the new credentials before applying changes.
Copy
curl --request PUT \
--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": "new-db.example.com",
"port": 5432,
"username": "dbuser",
"password": "newpassword",
"database": "analytics",
"schema": "public"
}
}'
Copy
{
"name": "production-postgres"
}
PUT
https://api.usedatabrain.com
/
api
/
v2
/
datasource
Copy
curl --request PUT \
--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": "new-db.example.com",
"port": 5432,
"username": "dbuser",
"password": "newpassword",
"database": "analytics",
"schema": "public"
}
}'
Copy
{
"name": "production-postgres"
}
Update an existing datasource’s credentials or configuration. The API validates the new credentials, tests the connection, and automatically refreshes the cached schema.
You can only update datasources that already exist in your organization. The datasource is identified by the
name field in the credentials. After updating, the schema will be automatically re-cached.Endpoint
Copy
PUT https://api.usedatabrain.com/api/v2/datasource
Self-hosted Databrain Endpoint
Copy
PUT <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. Must match the existing datasource type. See Create Datasource for supported types.
Updated connection credentials for the datasource. Must include the
name field matching the existing datasource name.The
credentials.name field must match the exact name of the existing datasource you want to update. This name is used to identify which datasource to update.The name of the existing datasource to update. Must match exactly as it was created.
Show Finding datasource names
Show Finding datasource names
- Use the List Datasources API to see all datasource names
- Check the response from datasource creation
- Available in the DataBrain dashboard when viewing datasources
Multi-tenant configuration for the datasource. Defines how data is isolated between different tenants/clients. Optional - if not provided, existing tenancy settings will remain unchanged.
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
- If the datasource doesn’t have existing tenancy settings, new settings will be created
- If tenancy settings already exist, they will be updated with the new values
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
You must provide all required fields for the datasource type, even if only some values are changing. Partial updates are not supported.When updating credentials, provide the complete credential structure for the datasource type. Partial updates are not supported.
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 updated 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 not found |
CREDENTIAL_TEST_FAILED | 400 | Connection test failed |
AUTHENTICATION_ERROR | 401 | Invalid or missing service token |
SCHEMA_CACHE_FAILED | 500 | Schema caching failed |
DATASOURCE_NOT_FOUND | 404 | The specified datasource does not exist |
TENANCY_SETTINGS_CREATE_FAILED | 500 | Failed to create tenancy settings for the datasource |
TENANCY_SETTINGS_UPDATE_FAILED | 500 | Failed to update existing tenancy settings |
INTERNAL_SERVER_ERROR | 500 | Server error occurred |
Next Steps
⌘I