> ## 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.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.omni.co/feedback
```json
{
"path": "/api/connections/create-connection",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Create connection
> Creates a new database connection. See the **Parameters**
## OpenAPI
````yaml /api/openapi.yaml post /v1/connections
openapi: 3.1.0
info:
title: Omni API
description: >
The Omni REST API provides programmatic access to your Omni instance for
managing users, documents, queries, schedules, and more.
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: AI
description: AI-powered query generation
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Content
description: Unified content retrieval (documents and folders)
- name: Content migration
description: Export and import dashboards
- name: Content validator
description: Validate content against models and perform find/replace operations
- name: Dashboard downloads
description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
- name: Dashboard filters and controls
description: Read and update dashboard filter and control default values
- name: dbt
description: Manage dbt configuration for connections
- name: Documents
description: Create, retrieve, and manage documents
- name: Document favorites
description: Favorite and unfavorite documents
- name: Document labels
description: Apply and manage labels on documents
- name: Document permissions
description: Manage document-level access
- name: Labels
description: >
Manage labels in an organization. Labels can be applied to documents and
folders to help organize and categorize content.
**Label types:**
- **Basic labels**: Can be created and managed by any user
- **Verified labels**: Indicate curated or officially sanctioned content.
Admin-only.
- **Homepage labels**: Appear on the organization homepage. Admin-only.
- name: Folders
description: Create and organize content folders
- name: Folder permissions
description: Manage folder-level access
- name: Jobs
description: Check status of asynchronous jobs
- name: Models
description: Create and manage data models
- name: Model branches
description: Manage model branches and merge changes
- name: Model git configuration
description: Manage git configuration for shared models
- name: Queries
description: Execute workbook queries
- name: Schedules
description: Create and manage scheduled tasks
- name: Schedule recipients
description: Manage schedule recipients
- name: Schema refresh schedules
description: Manage automated schema refresh schedules for connections
- name: Topics
description: Retrieve topic information from models
- name: Uploads
description: Manage file uploads
- name: Users
description: Manage users
- name: User attributes
description: Manage user attribute definitions
- name: User groups
description: Manage user groups
- name: User model roles
description: Manage model and connection role assignments for users
- name: User group model roles
description: Manage model and connection role assignments for user groups
- name: Uploads
description: Manage CSV and spreadsheet uploads
paths:
/v1/connections:
post:
tags:
- Connections
summary: Create connection
description: |
Creates a new database connection. See the **Parameters**
operationId: createConnection
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- dialect
- name
- passwordUnencrypted
properties:
dialect:
$ref: '#/components/schemas/Dialect'
name:
type: string
description: A descriptive name for the connection
host:
type: string
description: >
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:
type: integer
description: >
The port number for the database connection.
Not required for Snowflake, MotherDuck, BigQuery,
Databricks, and Athena.
database:
type: string
description: |
The default database/catalog to connect to.
- **BigQuery** - Provide the project ID
- **Athena** - Provide the data catalog
username:
type: string
description: >
The username to authenticate with.
- **MotherDuck** - Not required
- **BigQuery** - Provide client email from the service
account
passwordUnencrypted:
type: string
description: >
The password to authenticate with.
- **BigQuery** - This must be the JSON service account key
file content
- **Snowflake** with keypair authentication - Can be omitted
baseRole:
type: string
description: >
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](/administration/users/custom-roles) defined
for your organization
warehouse:
type: string
description: |
**Required for**:
- **Snowflake** - Specify the warehouse
- **Databricks** - Specify the HTTP path
includeSchemas:
type: string
description: >-
Comma-separated list of schemas to include. Leave empty to
include all schemas.
includeOtherCatalogs:
type: string
description: >
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:
type: string
description: |
**Required for MSSQL.** The default schema to use.
queryTimeoutSeconds:
type: integer
description: >-
The timeout in seconds for queries. Maximum value is `3600`
(1 hour). Only applicable for databases that support query
timeouts.
maximum: 3600
default: 900
region:
type: string
description: |
**Required for BigQuery and Athena connections.**
- **BigQuery** - Specify a region like `us`
- **Athena** - Specify an AWS region like `us-east-1`
maxBillingBytes:
type: string
description: >
**Applicable for BigQuery.** Maximum bytes that can be
billed for a BigQuery query.
scratchSchema:
type: string
description: >-
Schema to use for data input (upload) tables. If not
specified, a suitable default will be chosen.
systemTimezone:
type: string
description: The timezone to use for the system.
default: UTC
queryTimezone:
type: string
description: The timezone to use for queries.
default: NONE
allowsUserSpecificTimezones:
type: boolean
description: Whether to allow users to specify their own timezones.
default: false
trustServerCertificate:
type: boolean
description: >
**Applicable for MSSQL, Exasol, and ClickHouse.** Whether to
trust the server certificate.
default: false
privateKey:
type: string
description: >
**Applicable for Snowflake only.** An RSA key for keypair
authentication. Omni will automatically add PEM headers if
none are provided.
acceptsLicense:
type: boolean
description: >
**Applicable for Oracle.** Whether to accept the license
terms.
authenticationType:
type: string
description: >
**Applicable for BigQuery, MSSQL, Snowflake, Databricks, and
Athena.** The authentication method to use.
awsRoleArn:
type: string
description: >
**Applicable for Athena.** The AWS role ARN to assume for
the connection.
enableDbSemanticLayerIntegration:
type: boolean
description: >
Whether to enable the database's semantic layer integration:
- **Snowflake** - [Snowflake semantic
views](/connect-data/snowflake-semantic-views)
- **Databricks** - [Databricks Unity
Catalog](/connect-data/databricks-unity-catalog-integration)
enableDbSemanticLayerTopics:
type: boolean
description: >
**Applicable for Snowflake and Databricks.** Whether to
enable database semantic layer topics.
externalOauthAudience:
type: string
description: >
**Applicable for Snowflake.** The audience for [external
OAuth
authentication](/connect-data/oauth/snowflake/external-okta).
externalOauthAuthorizationUrl:
type: string
description: >
**Applicable for Snowflake.** The authorization URL for
[external OAuth
authentication](/connect-data/oauth/snowflake/external-okta).
externalOauthTokenUrl:
type: string
description: >
**Applicable for Snowflake.** The token URL for [external
OAuth
authentication](/connect-data/oauth/snowflake/external-okta).
hostOverride:
type: string
description: |
**Applicable for Snowflake.** Override for the host value.
inferRelationshipsFromForeignKeys:
type: boolean
description: >
**Applicable for Postgres and Snowflake.** Whether to
automatically infer relationships from foreign key
constraints.
oauthClientId:
type: string
description: >
**Applicable for
[Snowflake](/connect-data/oauth/snowflake/native) and
Databricks.** The OAuth client ID for native OAuth.
oauthClientSecretUnencrypted:
type: string
description: >
**Applicable for Snowflake and Databricks.** The unencrypted
OAuth client secret for [native
OAuth](/connect-data/oauth/snowflake/native).
offloadedSchemas:
type: string
description: >
**Applicable for all dialects.** Comma-separated list of
schemas to offload. See [Offloading
schemas](/connect-data/offloading-schemas) for more
information.
useMachineAuth:
type: boolean
description: >
**Applicable for Athena and Databricks.** Whether to use
machine authentication.
examples:
BigQuery:
summary: BigQuery
value:
dialect: bigquery
name: My BigQuery Connection
region: us
passwordUnencrypted:
defaultSchema: my_dataset
includeSchemas: dataset1,dataset2
includeOtherCatalogs: other_project1,other_project2
maxBillingBytes: '1000000000'
MySQL:
summary: MySQL
value:
dialect: mysql
name: My MySQL Connection
host: mysql.example.com
port: 3306
database: mydb
username: dbuser
passwordUnencrypted: mypassword
includeSchemas: public,analytics
queryTimeoutSeconds: 900
Postgres:
summary: PostgreSQL
value:
dialect: postgres
name: My Postgres Connection
host: postgres.example.com
port: 5432
database: mydb
username: dbuser
passwordUnencrypted: mypassword
includeSchemas: public,analytics
queryTimeoutSeconds: 900
Snowflake:
summary: Snowflake
value:
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
responses:
'201':
description: Connection created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: string
format: uuid
description: Connection ID
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
components:
schemas:
Dialect:
type: string
description: |
The database dialect.
enum:
- athena
- bigquery
- clickhouse
- databricks
- databricks_lakebase
- exasol
- mariadb
- motherduck
- mssql
- mysql
- oracle
- postgres
- redshift
- sap_hana
- snowflake
- starrocks
- trino
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
BadRequest:
description: Bad Request - Invalid parameters or request body
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden - Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Too Many Requests - Rate limit exceeded (60 requests/minute)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Can be either an [Organization API
Key](/api/authentication#organization-api-keys) or [Personal Access
Token (PAT)](/api/authentication#personal-access-tokens-pat).
Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
orgApiKey:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Requires an [Organization API
Key](/api/authentication#organization-api-keys). Personal Access Tokens
(PATs) are not supported for this endpoint.
Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`
````