Skip to main content

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.

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.

Parameters​

Loading parameters...

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"
}
FieldTypeDescription
successbooleanIndicates if the connection was created successfully
datastringThe UUID of the newly created connection
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
IssueError detail
Invalid JSONBad Request: Invalid JSON
Invalid dialectInvalid connection dialect
Invalid methodInvalid method
Missing required fieldsBad Request: <field>: Required
Invalid Snowflake hostBad Request: host: Please only include your Snowflake account identifier
403 Forbidden
{
  "detail": "Permission denied",
  "status": 403
}
IssueError detail
Insufficient permissionsPermission 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 '{
  "baseRole": "CONNECTION_ADMIN"
}'

Parameters​

Loading parameters...

Response​

200 OK

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

{
  "success": true,
  "message": "Updated connection default role and user attribute settings."
}

The response message varies based on what was updated:

  • "Updated connection default role and user attribute settings." - When both role and user attributes were updated
  • "Updated environment user attribute settings." - When only user attributes were updated
  • "Updated connection default role." - When only the role was updated
  • "No updates were made to the connection." - When no changes were applied
FieldTypeDescription
successbooleanIndicates if the connection was updated successfully
messagestringA message describing the action taken
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
IssueError detail
Invalid JSONBad Request: Invalid JSON
Invalid methodInvalid method
Empty request bodyBad Request: Empty request body
Missing required fieldsBad Request: <field>: Required
Invalid base roleBad Request: baseRole: Invalid enum value
User attribute already in useUser attribute value "value" is already in use
403 Forbidden
{
  "detail": "Permission denied",
  "status": 403
}
IssueError detail
Insufficient permissionsPermission denied
404 Not Found
{
  "detail": "Connection not found",
  "status": 404
}
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.

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

Parameters​

Note: All parameters must be provided as query parameters.

Loading parameters...

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
    }
  ]
}
FieldTypeDescription
connectionsarrayArray of connection objects
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
IssueError detail
Invalid or unrecognized query parameterBad Request: formErrors: Unrecognized key(s) in object: '<invalidParam>'
Invalid sort fieldBad Request: sortField: Invalid enum value. Expected 'database' | 'dialect' | 'name', received '<invalidField>'
Invalid dialect valueInvalid 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.