Create connection

Creates a new database connection. See below for a handful of example requests.

BigQuery
MySQL
PostgreSQL
Snowflake

Create a BigQuery connection

curl -L -X POST 'https://{your-instance}.omniapp.co/api/v1/connections' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "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"
}'

Note: For BigQuery, you must include a service account JSON file encoded as a string in the passwordUnencrypted field.

Create a MySQL connection

curl -L -X POST 'https://{your-instance}.omniapp.co/api/v1/connections' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "dialect": "mysql",
  "name": "My MySQL Connection",
  "host": "mysql.example.com",
  "port": 3306,
  "database": "mydb",
  "username": "dbuser",
  "passwordUnencrypted": "mypassword",
  "includeSchemas": "public,analytics",
  "queryTimeoutSeconds": 900
}'

Create a PostgreSQL connection

curl -L -X POST 'https://{your-instance}.omniapp.co/api/v1/connections' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "dialect": "postgres",
  "name": "My Postgres Connection",
  "host": "postgres.example.com",
  "port": 5432,
  "database": "mydb",
  "username": "dbuser",
  "passwordUnencrypted": "mypassword",
  "includeSchemas": "public,analytics",
  "queryTimeoutSeconds": 900
}'

Create a Snowflake connection

curl -L -X POST 'https://{your-instance}.omniapp.co/api/v1/connections' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "dialect": "snowflake",
  "name": "My Snowflake Connection",
  "host": "myaccount",
  "database": "MYDB",
  "username": "dbuser",
  "passwordUnencrypted": "mypassword",
  "warehouse": "COMPUTE_WH",
  "includeSchemas": "PUBLIC,ANALYTICS",
  "includeOtherCatalogs": "OTHER_DB1,OTHER_DB2",
  "queryTimeoutSeconds": 900
}'

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,

exasol,

mariadb,

motherduck,

mssql,

mysql,

postgres,

redshift,

snowflake,

starrocks,

trino

name

string

required

A descriptive name for the connection

passwordUnencrypted

string

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

host

string

The hostname or IP address of the database server.

Not required for MotherDuck
For Snowflake, provide only the account identifier (e.g., myaccount not myaccount.snowflakecomputing.com)
For BigQuery, this is 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.

For BigQuery, this is the project ID
For Athena, this is the data catalog

username

string

The username to authenticate with.

Not required for MotherDuck
For BigQuery, this is the client email from the service account

baseRole

enum<string>

The default role for users accessing the connection

Available options:

NO_ACCESS,

VIEWER,

RESTRICTED_QUERIER,

QUERIER,

MODELER,

CONNECTION_ADMIN

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

The default schema to use. Required for MSSQL.

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.

For BigQuery, specify a region like us
For Athena, specify an AWS region like us-east-1

maxBillingBytes

string

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

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

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

privateKey

string

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

Response

Connection created successfully

success

boolean

data

string<uuid>

Connection ID

Getting started

Endpoints

Guides

Authorizations

Body

Response