Skip to main content
POST
/
v1
/
connections
curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dialect": "bigquery",
  "name": "My BigQuery Connection",
  "region": "us",
  "passwordUnencrypted": "<SERVICE_ACCOUNT_JSON_FILE>",
  "defaultSchema": "my_dataset",
  "includeSchemas": "dataset1,dataset2",
  "includeOtherCatalogs": "other_project1,other_project2",
  "maxBillingBytes": "1000000000"
}
'
{
  "success": true,
  "data": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Documentation Index

Fetch the complete documentation index at: https://docs.omni.co/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Body

application/json
​
dialect
enum<string>
required

The database dialect.

Available options:
athena,
bigquery,
clickhouse,
databricks,
databricks_lakebase,
exasol,
mariadb,
motherduck,
mssql,
mysql,
oracle,
postgres,
redshift,
sap_hana,
snowflake,
starrocks,
trino
​
name
string
required

A descriptive name for the connection

​
passwordUnencrypted
string
required

The password to authenticate with.

  • BigQuery - This must be the JSON service account key file content
  • Snowflake with keypair authentication - Can be omitted
​
host
string

The hostname or IP address of the database server.

  • MotherDuck - Not required
  • Snowflake - Provide only the account identifier (e.g., myaccount not myaccount.snowflakecomputing.com)
  • BigQuery - Automatically determined from the service account
​
port
integer

The port number for the database connection.

Not required for Snowflake, MotherDuck, BigQuery, Databricks, and Athena.

​
database
string

The default database/catalog to connect to.

  • BigQuery - Provide the project ID
  • Athena - Provide the data catalog
​
username
string

The username to authenticate with.

  • MotherDuck - Not required
  • BigQuery - Provide client email from the service account
​
baseRole
string

The default role for users accessing the connection. Available roles include:

  • VIEWER - Can view the model
  • QUERIER - Can view and query the model
  • QUERY_TOPICS - Can query specific topics. Equivalent to Restricted Querier.
  • MODELER - Can edit and model the data
  • CONNECTION_ADMIN - Full administrative access to the connection
  • NO_ACCESS - No access to the model
  • Custom roles defined for your organization
​
warehouse
string

Required for:

  • Snowflake - Specify the warehouse
  • Databricks - Specify the HTTP path
​
includeSchemas
string

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

​
includeOtherCatalogs
string

Comma-separated list of other catalogs/databases to include. Only applicable for databases that support multi-catalog queries: BigQuery, Snowflake, MotherDuck, Databricks, Trino, Athena.

​
defaultSchema
string

Required for MSSQL. The default schema to use.

​
queryTimeoutSeconds
integer
default:900

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

Required range: x <= 3600
​
region
string

Required for BigQuery and Athena connections.

  • BigQuery - Specify a region like us
  • Athena - Specify an AWS region like us-east-1
​
maxBillingBytes
string

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

​
scratchSchema
string

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

​
systemTimezone
string
default:UTC

The timezone to use for the system.

​
queryTimezone
string
default:NONE

The timezone to use for queries.

​
allowsUserSpecificTimezones
boolean
default:false

Whether to allow users to specify their own timezones.

​
trustServerCertificate
boolean
default:false

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

​
privateKey
string

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

​
acceptsLicense
boolean

Applicable for Oracle. Whether to accept the license terms.

​
authenticationType
string

Applicable for BigQuery, MSSQL, Snowflake, Databricks, and Athena. The authentication method to use.

​
awsRoleArn
string

Applicable for Athena. The AWS role ARN to assume for the connection.

​
enableDbSemanticLayerIntegration
boolean

Whether to enable the database's semantic layer integration:

​
enableDbSemanticLayerTopics
boolean

Applicable for Snowflake and Databricks. Whether to enable database semantic layer topics.

​
externalOauthAudience
string

Applicable for Snowflake. The audience for external OAuth authentication.

​
externalOauthAuthorizationUrl
string

Applicable for Snowflake. The authorization URL for external OAuth authentication.

​
externalOauthTokenUrl
string

Applicable for Snowflake. The token URL for external OAuth authentication.

​
hostOverride
string

Applicable for Snowflake. Override for the host value.

​
inferRelationshipsFromForeignKeys
boolean

Applicable for Postgres and Snowflake. Whether to automatically infer relationships from foreign key constraints.

​
oauthClientId
string

Applicable for Snowflake and Databricks. The OAuth client ID for native OAuth.

​
oauthClientSecretUnencrypted
string

Applicable for Snowflake and Databricks. The unencrypted OAuth client secret for native OAuth.

​
offloadedSchemas
string

Applicable for all dialects. Comma-separated list of schemas to offload. See Offloading schemas for more information.

​
useMachineAuth
boolean

Applicable for Athena and Databricks. Whether to use machine authentication.

Response

Connection created successfully

​
success
boolean
​
data
string<uuid>

Connection ID