> ## 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/dbt/update-dbt-environment",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Update dbt environment
>
This endpoint requires **Connection Admin** permissions for the connection.
Updates an existing dbt environment on the specified connection. All fields are optional; only the provided fields will be updated.
## OpenAPI
````yaml /api/openapi.yaml put /v1/connections/{connectionId}/dbt/environments/{environmentId}
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/{connectionId}/dbt/environments/{environmentId}:
put:
tags:
- dbt
summary: Update dbt environment
description: >
This endpoint requires **Connection Admin** permissions for the connection.
Updates an existing dbt environment on the specified connection. All
fields are optional; only the provided fields will be updated.
operationId: updateDbtEnvironment
parameters:
- name: connectionId
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the connection
- name: environmentId
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the dbt environment
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
description: The name of the dbt environment
example: Development
targetSchema:
type: string
minLength: 1
description: The target schema for the environment
example: dev_schema
ownerId:
type: string
format: uuid
nullable: true
description: >
**Only valid with Organization API keys.** The user ID of
the owner for the dbt environment. Personal Access Tokens
(PATs) automatically use the authenticated user as the
owner.
example: 550e8400-e29b-41d4-a716-446655440000
targetDatabase:
type: string
nullable: true
description: Target database override
example: analytics_dev
targetName:
type: string
nullable: true
description: Target name override
example: custom_target
targetRole:
type: string
nullable: true
description: Target role override
example: developer
variables:
type: array
description: >
Environment variables for the dbt environment. To update
existing variables, include the variable `id` field. New
variables should omit the `id` field.
items:
type: object
required:
- name
- value
- isSecret
properties:
id:
type: string
format: uuid
description: >-
Variable identifier. Required for updating existing
variables, otherwise omit.
example: b2c3d4e5-f6a7-8901-bcde-f12345678901
name:
type: string
minLength: 1
description: >-
Variable name. Required for new variables, otherwise
omit.
example: DBT_TARGET
value:
type: string
description: >-
Variable value. Required for new variables, otherwise
omit or set to `null` to keep the existing value for
secrets.
example: production
isSecret:
type: boolean
description: >-
Whether the variable value is secret. Required for new
and updating existing variables.
example: false
examples:
basic:
summary: Update name and schema
value:
name: Development
targetSchema: dev_schema
withOwner:
summary: Update ownership
value:
name: Production
ownerId: 550e8400-e29b-41d4-a716-446655440000
withVariables:
summary: Update with variables
value:
name: Production
targetSchema: dev_schema
variables:
- id: b2c3d4e5-f6a7-8901-bcde-f12345678901
name: DBT_TARGET
value: staging
isSecret: false
- name: NEW_VAR
value: new_value
isSecret: false
responses:
'200':
description: dbt environment updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DbtEnvironment'
example:
id: 247dc6dc-2a58-4688-9521-c5ed3e99c1e8
name: Development
isDefaultEnvironment: false
ownerId: 550e8400-e29b-41d4-a716-446655440000
targetDatabase: analytics_dev
targetName: custom_target
targetRole: developer
targetSchema: dev_schema
variables:
id: b2c3d4e5-f6a7-8901-bcde-f12345678901
name: DBT_TARGET
value: staging
isSecret: false
'400':
description: |
Bad Request
Possible error messages:
- Invalid request body
- User specified in `ownerId` is not a member of the organization
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: >
Forbidden
Possible causes:
- Insufficient permissions. **Connection Admin** permissions for the
connection are required.
- Non-admin user attempting to set `ownerId` for another user
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Connection or dbt environment not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
components:
schemas:
DbtEnvironment:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the dbt environment
name:
type: string
description: The name of the dbt environment
isDefaultEnvironment:
type: boolean
description: Whether this is the default environment
ownerId:
type: string
format: uuid
nullable: true
description: The user ID of the owner of the dbt environment, or null
targetDatabase:
type: string
nullable: true
description: Target database override
targetName:
type: string
nullable: true
description: Target name override
targetRole:
type: string
nullable: true
description: Target role override
targetSchema:
type: string
description: Target schema for the environment
variables:
type: array
description: Environment variables
items:
type: object
properties:
id:
type: string
format: uuid
description: Variable identifier
name:
type: string
description: Variable name
value:
type: string
nullable: true
description: >
Variable value. If `isSecret: true`, this value will be `null`
in responses to protect sensitive information.
isSecret:
type: boolean
description: |
Whether the variable value is secret.
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
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`
````