Connection APIs

These APIs are in beta

The connection APIs are in beta and may have future breaking changes.

The connection APIs allow you to programmatically create and manage database connections in your Omni instance.

Create a connection

Creates a new database connection.

BigQuery

POST /api/unstable/connections

curl -X POST 'https://myorg.omniapp.co/api/unstable/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.

MySQL

POST /api/unstable/connections

curl -X POST 'https://myorg.omniapp.co/api/unstable/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
}'

PostgreSQL

POST /api/unstable/connections

curl -X POST 'https://myorg.omniapp.co/api/unstable/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
}'

Snowflake

POST /api/unstable/connections

curl -X POST 'https://myorg.omniapp.co/api/unstable/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
}'

Parameters

Parameter	Type	Required	Default	Description
dialect	string	Yes ✓	-	The database dialect. Must be one of: bigquery - Google BigQuery mysql - MySQL postgres - PostgreSQL redshift - Amazon Redshift snowflake - Snowflake motherduck - MotherDuck mssql - Microsoft SQL Server databricks - Databricks clickhouse - ClickHouse trino - Trino athena - Amazon Athena exasol - Exasol starrocks - StarRocks
name	string	Yes ✓	-	A descriptive name for the connection.
host	string	Yes* ✓	-	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	number	Yes* ✓	Varies by dialect	The port number for the database connection. Not required for Snowflake, MotherDuck, BigQuery, Databricks, and Athena.
database	string	Yes ✓	-	The default database/catalog to connect to. For BigQuery, this is the project ID For Athena, this is the data catalog
username	string	Yes* ✓	-	The username to authenticate with. Not required for MotherDuck For BigQuery, this is the client email from the service account
passwordUnencrypted	string	Yes* ✓	-	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.
includeSchemas	string	No X	""	Comma-separated list of schemas to include. Leave empty to include all schemas.
includeOtherCatalogs	string	No X	""	Comma-separated list of other catalogs/databases to include. Only applicable for databases that support multi-catalog queries: BigQuery, Snowflake, MotherDuck, Databricks, Trino, Athena.
warehouse	string	Yes* ✓	-	Required for: Snowflake - Specify the warehouse Databricks - Specify the HTTP path
defaultSchema	string	No X	-	The default schema to use. Required for MSSQL.
queryTimeoutSeconds	number	No X	900	The timeout in seconds for queries. Maximum value is 3600 (1 hour). Only applicable for databases that support query timeouts.
trustServerCertificate	boolean	No X	false	Whether to trust the server certificate. Only applicable for MSSQL, Exasol, and ClickHouse.
region	string	Yes* ✓	"us" for BigQuery, "us-east-1" for Athena	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	No X	null	Only applicable for BigQuery. Maximum bytes that can be billed for a BigQuery query.
scratchSchema	string	No X	null	Schema to use for data input (upload) tables. If not specified, a suitable default will be chosen.
systemTimezone	string	No X	UTC	The timezone to use for the system.
queryTimezone	string	No X	"NONE"	The timezone to use for queries.
allowsUserSpecificTimezones	boolean	No X	false	Whether to allow users to specify their own timezones.

Database-specific requirements

BigQuery

tip

Refer to the BigQuery setup guide for help retrieving the required information.

The following is required when creating a BigQuery connection:

• A service account JSON key file in the passwordUnencrypted field. The service account file must be a valid JSON document with the following structure:

  {
    "type": "service_account",
    "project_id": "your-project-id",
    "private_key_id": "key-id",
    "private_key": "-----BEGIN PRIVATE KEY-----\nkey-content\n-----END PRIVATE KEY-----\n",
    "client_email": "service-account-email@your-project-id.iam.gserviceaccount.com",
    "client_id": "client-id",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email%40your-project-id.iam.gserviceaccount.com"
  }

• A region (defaults to "us")

You can also optionally set a maxBillingBytes limit.

Databricks

tip

Refer to the Databricks setup guide for help retrieving the required information.

To create a Databricks connection, specify the warehouse field with the HTTP path value.

Additionally:

• port is not required
• Set useMachineAuth to true for machine-based authentication

MotherDuck

tip

Refer to the MotherDuck setup guide for help retrieving the required information.

To create a MotherDuck connection, the passwordUnencrypted field should contain your MotherDuck token. The host, port, and username fields aren't required.

Snowflake

tip

Refer to the Snowflake setup guide for help retrieving the required information.

The following is required when creating a Snowflake connection:

• Your account identifier in the host field. This should be a value like myorg, not myorg.snowflakecomputing.com
• A warehouse

A port isn't required.

Response

201 Created

Successful requests will return a 201 Created status and a response body similar to the following:

{
  "success": true,
  "data": "c0f12353-4817-4398-bcc0-d501e6dd2f64"
}

Field	Type	Description
success	boolean	Indicates if the connection was created successfully
data	string	The UUID of the newly created connection

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Invalid JSON	Bad Request: Invalid JSON
Invalid dialect	Invalid connection dialect
Invalid method	Invalid method
Missing required fields	Bad Request: <field>: Required
Invalid Snowflake host	Bad Request: host: Please only include your Snowflake account identifier

403 Forbidden

{
  "detail": "Permission denied",
  "status": 403
}

Issue	Error detail
Insufficient permissions	Permission denied

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Update a connection

Updates properties of an existing connection.

PATCH /api/unstable/connections/:connectionId

curl -X PATCH 'https://myorg.omniapp.co/api/unstable/connections/c0f12353-4817-4398-bcc0-d501e6dd2f64' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json' \
--d '{
  "userAttributeNameForConnectionEnvironments": "environment",
  "userAttributeValuesForDefaultEnvironment": "dev,prod"
}'

Parameters

Parameter	Type	Required	Default	Description
connectionId	URL parameter	Yes ✓	-	The UUID of the connection to update.
userAttributeNameForConnectionEnvironments	string | null	Yes ✓	-	The name of the user attribute to use for connection environments. To remove the attribute, set to null.
userAttributeValuesForDefaultEnvironment	string | null	Yes ✓	-	A comma-separated list of user attribute values that will be associated with the default connection environment. For example: "dev,prod,staging" To remove the attribute values, set to null.

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "success": true,
  "message": "Updated dynamic user attribute settings."
}

If user attribute settings were removed:

{
  "success": true,
  "message": "Removed dynamic user attribute settings."
}

Field	Type	Description
success	boolean	Indicates if the connection was updated successfully
message	string	A message describing the action taken

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Invalid JSON	Bad Request: Invalid JSON
Invalid method	Invalid method
Missing userAttributeNameForConnectionEnvironments	Bad Request: userAttributeNameForConnectionEnvironments: Invalid input
Missing userAttributeValuesForDefaultEnvironment	Bad Request: userAttributeValuesForDefaultEnvironment: Invalid input
Both parameters missing	Bad Request: userAttributeNameForConnectionEnvironments: Invalid input, userAttributeValuesForDefaultEnvironment: Invalid input
User attribute already in use	User attribute value "value" is already in use

403 Forbidden

{
  "detail": "Permission denied",
  "status": 403
}

Issue	Error detail
Insufficient permissions	Permission denied

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

List connections

Retrieves a list of database connections with optional filtering and sorting.

Basic request

GET /api/unstable/connections

curl -X GET 'https://myorg.omniapp.co/api/unstable/connections' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Filtering by name

GET /api/unstable/connections?name=<n>

curl -X GET 'https://myorg.omniapp.co/api/unstable/connections?name=Production' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Filtering by dialect

GET /api/unstable/connections?dialect=<dialect>

curl -X GET 'https://myorg.omniapp.co/api/unstable/connections?dialect=postgres,mysql' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Custom sorting

GET /api/unstable/connections?sortField=<field>&sortDirection=<direction>

curl -X GET 'https://myorg.omniapp.co/api/unstable/connections?sortField=database&sortDirection=asc' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Include deleted

GET /api/unstable/connections?includeDeleted=true

curl -X GET 'https://myorg.omniapp.co/api/unstable/connections?includeDeleted=true' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Parameters

Note: All parameters must be provided as query parameters.

Parameter	Type	Required	Default	Description
name	string	No X	-	Filter connections by name (case-insensitive, partial matching).
database	string	No X	-	Filter connections by database name (case-insensitive, partial matching).
dialect	string	No X	-	Filter connections by dialect(s). For multiple dialects, provide a comma-separated list (e.g., postgres,mysql). Valid values: athena, bigquery, clickhouse, databricks, exasol, motherduck, mssql, mysql, postgres, redshift, snowflake, starrocks, trino
includeDeleted	boolean	No X	false	When set to true, includes connections that have been deleted. Default is false, which returns only active connections.
sortField	string	No X	name	Field to sort connections by. Valid values: name - Sort by connection name dialect - Sort by database dialect database - Sort by database name
sortDirection	string	No X	desc	Direction for sorting. Valid values: asc - Ascending order (A-Z, 0-9) desc - Descending order (Z-A, 9-0)

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "connections": [
    {
      "id": "c0f12353-4817-4398-bcc0-d501e6dd2f64",
      "name": "Production Database",
      "dialect": "postgres",
      "database": "prod_db",
      "deletedAt": null,
      "userAttributeNameForConnectionEnvironments": "environment",
      "userAttributeValuesForDefaultEnvironment": ["prod"],
      "branchConnectionEnvironmentOverridesUserAttr": false,
      "environmentConnectionSwitchesSchemaModel": false
    },
    {
      "id": "789e0123-e45b-67d8-a456-426614174000",
      "name": "Development Database",
      "dialect": "mysql",
      "database": "dev_db",
      "deletedAt": null,
      "userAttributeNameForConnectionEnvironments": null,
      "userAttributeValuesForDefaultEnvironment": null,
      "branchConnectionEnvironmentOverridesUserAttr": false,
      "environmentConnectionSwitchesSchemaModel": false
    }
  ]
}

Field	Type	Description
connections	array	Array of connection objects

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Invalid or unrecognized query parameter	Bad Request: formErrors: Unrecognized key(s) in object: '<invalidParam>'
Invalid sort field	Bad Request: sortField: Invalid enum value. Expected 'database' | 'dialect' | 'name', received '<invalidField>'
Invalid dialect value	Invalid dialect(s): <invalidDialect>

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.