Sign in

v4

latestOpenAPI 3.1.02026-08-01207318738.7 KB
Connections

Create connection

Create a new database connection. The request body varies by dialect - see dialect-specific documentation for required fields.

post/api/v1/connections

Request body

acceptsLicenseboolean

Acceptance of the license terms. Required for Oracle connections.

allowsUserSpecificTimezonesboolean

Whether to allow users to specify their own timezones

alwaysScopeViewNamesboolean

Whether to always include schema (and catalog) prefixes in generated view names, even for tables in the default schema. Defaults to true for dialects that support multiple catalogs, false otherwise.

authenticationTypestring

Authentication type. Dialect-specific; known values are aws-access-key, aws-cross-account-role, databricks-oauth-m2m, databricks-personal-access-token, databricks-oauth-user, mssql-sql-authentication, mssql-active-directory-password, mssql-active-directory-service-principal, snowflake-oauth-user, snowflake-external-oauth-user, snowflake-password, snowflake-keypair, bigquery-oauth-user, bigquery-byo-oauth-user, bigquery-service-account, bigquery-workload-identity-federation. Applicable for BigQuery, MSSQL, Snowflake, Databricks, and Athena.

awsRoleArnstring

AWS IAM role ARN. Applicable for Athena only.

baseRole'NO_ACCESS' | 'VIEWER' | 'RESTRICTED_QUERIER' | 'QUERIER' | 'MODELER' | 'CONNECTION_ADMIN'

The default role for users accessing the connection

databasestring

The default database/catalog to connect to. For BigQuery, this is the project ID. For Athena, this is the data catalog.

defaultSchemastring

The default schema to use. Required for MSSQL.

dialect'bigquery' | 'mysql' | 'postgres' | 'redshift' | 'exasol' | 'snowflake' | 'motherduck' | 'mssql' | 'databricks' | 'databricks_lakebase' | 'clickhouse' | 'trino' | 'athena' | 'starrocks' | 'mariadb' | 'oracle' | 'sap_hana' required

The database dialect

enableDbSemanticLayerIntegrationboolean

Enable the dialect-native semantic layer integration. Applicable for Snowflake and Databricks.

enableDbSemanticLayerTopicsboolean

Enable the dialect-native semantic layer topics. Applicable for Snowflake and Databricks.

externalOauthAudiencestring

External OAuth audience claim. Applicable for Snowflake.

externalOauthAuthorizationUrlstring uri

External OAuth authorization URL (must be HTTPS). Applicable for Snowflake.

externalOauthTokenUrlstring uri

External OAuth token URL (must be HTTPS). Applicable for Snowflake.

hoststring

The hostname or IP address of the database server. For Snowflake, provide only the account identifier.

hostOverridestring

Custom Snowflake host (when not using the account identifier). Mutually exclusive with host.

includeOtherCatalogsstring

Comma-separated list of other catalogs/databases to include. Only applicable for databases that support multi-catalog queries.

includeSchemasstring

Comma-separated list of schemas to include. Leave empty to include all schemas.

inferRelationshipsFromColumnNamesboolean

Whether to infer relationships from column-name conventions during schema refresh. Defaults to true.

inferRelationshipsFromForeignKeysboolean

Whether to infer relationships from declared foreign keys during schema refresh. Currently honored for Postgres and Snowflake.

maxBillingBytesstring

Maximum bytes that can be billed for a BigQuery query. Applicable for BigQuery only.

namestring required

A descriptive name for the connection

oauthClientIdstring

OAuth client ID for admin schema refresh. Applicable for Snowflake and Databricks.

oauthClientSecretUnencryptedstring

OAuth client secret for admin schema refresh. Applicable for Snowflake and Databricks.

passwordUnencryptedstring required

The password to authenticate with. For BigQuery, this must be the JSON service account key file content. For Snowflake with keypair authentication, this can be omitted.

portinteger

The port number for the database connection. Not required for Snowflake, MotherDuck, BigQuery, Databricks, and Athena.

privateKeystring

An RSA key for keypair authentication. Omni will automatically add PEM headers if none are provided. Applicable for Snowflake only.

queryTimeoutSecondsinteger

The timeout in seconds for queries. Maximum value is 3600 (1 hour). Only applicable for databases that support query timeouts.

queryTimezonestring

The timezone to use for queries

regionstring

Required for BigQuery and Athena connections. For BigQuery, specify a region like "us". For Athena, specify an AWS region like "us-east-1".

scratchSchemastring

Schema to use for data input (upload) tables. If not specified, a suitable default will be chosen.

systemTimezonestring

The timezone to use for the system

trustServerCertificateboolean

Whether to trust the server certificate. Applicable for MSSQL, Exasol, ClickHouse, Trino, and SAP HANA.

useMachineAuthboolean

Whether to authenticate using machine credentials (OAuth M2M). Applicable for Athena and Databricks.

usernamestring

The username to authenticate with. For BigQuery, this is the client email from the service account.

warehousestring

Required for Snowflake (specify the warehouse) and Databricks (specify the HTTP path). May be omitted for Snowflake OAuth connections, in which case each user's Snowflake default warehouse applies.

wifAudiencestring

Full resource name of the workload identity pool provider. Required for BigQuery workload identity federation authentication.

wifServiceAccountEmailstring

Service account to impersonate for BigQuery workload identity federation authentication. When omitted, the federated identity is used directly.

Example request

{
  "acceptsLicense": true,
  "alwaysScopeViewNames": true,
  "authenticationType": "snowflake-password",
  "awsRoleArn": "arn:aws:iam::123456789012:role/OmniAthenaRole",
  "baseRole": "QUERIER",
  "database": "analytics_db",
  "defaultSchema": "public",
  "dialect": "snowflake",
  "externalOauthAuthorizationUrl": "https://oauth.example.com/authorize",
  "externalOauthTokenUrl": "https://oauth.example.com/token",
  "host": "myaccount",
  "hostOverride": "myaccount.snowflakecomputing.com",
  "includeOtherCatalogs": "other_project1,other_project2",
  "includeSchemas": "public,analytics",
  "inferRelationshipsFromColumnNames": true,
  "maxBillingBytes": "1000000000",
  "name": "Production Warehouse",
  "port": 5432,
  "queryTimeoutSeconds": 900,
  "queryTimezone": "NONE",
  "region": "us-east-1",
  "scratchSchema": "omni_scratch",
  "systemTimezone": "UTC",
  "username": "analytics_user",
  "warehouse": "COMPUTE_WH",
  "wifAudience": "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider",
  "wifServiceAccountEmail": "omni@my-project.iam.gserviceaccount.com"
}

Response

Connection created successfully

datastring uuid required

Created connection ID

successboolean required

Whether the operation succeeded

Example response

{
  "data": "550e8400-e29b-41d4-a716-446655440000",
  "success": true
}