# Omni Docs: Developers REST APIs ## REST APIs ### Getting started - [Omni REST APIs](https://docs.omni.co/api/index.md): Programmatically interact with your Omni instance with Omni's REST APIs. - [Omni API base URL](https://docs.omni.co/api/base-url.md): Find the base URL for requests to your Omni instance's REST APIs. - [API authentication](https://docs.omni.co/api/authentication.md): Authenticate your requests to the Omni API with an API token. - [Omni API versioning](https://docs.omni.co/api/versioning.md): Learn about the versioning strategy for and current status of Omni APIs. - [Omni API rate limiting](https://docs.omni.co/api/rate-limits.md): Understand Omni API rate limits and how to handle them in your integration. - [API Explorer](https://docs.omni.co/api/api-explorer.md): Interactively browse and test Omni API endpoints using the built-in API Explorer. - [Omni CLI](https://docs.omni.co/api/cli.md): Prefer the terminal? The Omni CLI wraps these REST APIs so you can query data, manage models, and automate workflows without hand-writing HTTP calls. ### Who am I? - [Get current identity and permissions](https://docs.omni.co/api/who-am-i/get-current-identity-and-permissions.md): Retrieve the authenticated caller's own identity, API key scope, organization role, and resolved per-model permissions. Useful for allowing a caller to determine if they can execute a specific action without attempting it. Pass `modelId` to scope `rolesByModel` to specific models. ### AI APIs - [Search Omni docs](https://docs.omni.co/api/ai/search-omni-docs.md): Search the Omni documentation using AI to answer questions about Omni features, configuration, modeling, dashboards, and more. Sends a natural language question and returns a synthesized answer with source links to the relevant documentation pages. #### Branding - [Get AI Agent branding](https://docs.omni.co/api/ai/get-ai-agent-branding.md): Return the organization's AI Agent's [branding configuration](/ai/settings/branding), including display name, custom logo URL, and copy for AI Agent landing surfaces. Falls back to Omni's default values when custom branding hasn't been configured. #### Conversations - [List AI conversations](https://docs.omni.co/api/ai/list-ai-conversations.md): List a user's recent AI conversations, ordered by most-recent activity. Each conversation includes an ID that can be passed as `conversationId` to subsequent [Create AI job](/api/ai/create-ai-job) requests to continue the thread. - [Get conversation](https://docs.omni.co/api/ai/get-conversation.md): Retrieve a conversation with its full message history — alternating user and assistant turns. Each assistant turn carries the originating `jobId` and an `omniChatUrl` deep link. #### Credit Controls - [Update AI credit controls](https://docs.omni.co/api/ai-credit-controls/update-ai-credit-controls.md): **Organization Admin** permissions are required for this endpoint. - [Get AI credit controls](https://docs.omni.co/api/ai-credit-controls/get-ai-credit-controls.md): **Organization Admin** permissions are required for this endpoint. - [Set individual users' AI credit limits](https://docs.omni.co/api/ai-credit-controls/set-individual-users-ai-credit-limits.md): **Organization Admin** permissions are required to use this endpoint. - [List individual users' AI credit limits](https://docs.omni.co/api/ai-credit-controls/list-individual-users-ai-credit-limits.md): **Organization Admin** permissions are required to use this endpoint. - [Set individual entity groups' AI credit limits](https://docs.omni.co/api/ai-credit-controls/set-individual-entity-groups-ai-credit-limits.md): **Organization Admin** permissions are required to use this endpoint. - [List individual entity groups' AI credit limits](https://docs.omni.co/api/ai-credit-controls/list-individual-entity-groups-ai-credit-limits.md): **Organization Admin** permissions are required to use this endpoint. #### Credit Usage - [Read individual users' AI credit usage](https://docs.omni.co/api/ai-credit-usage/read-individual-users-ai-credit-usage.md): **Organization Admin** permissions are required to use this endpoint. - [Read individual entity groups' AI credit usage](https://docs.omni.co/api/ai-credit-usage/read-individual-entity-groups-ai-credit-usage.md): **Organization Admin** permissions are required to use this endpoint. #### Evals - [Create an eval prompt set](https://docs.omni.co/api/ai-eval/create-an-eval-prompt-set.md): Create a new eval prompt set bound to a shared model. Initial prompts can be supplied; additional prompts can be added later via PATCH. - [Update an eval prompt set](https://docs.omni.co/api/ai-eval/update-an-eval-prompt-set.md): Update a prompt set's name, description, and/or prompts. When `prompts` is supplied, it fully replaces the existing list — existing prompts omitted from the list are deleted, entries without an `id` are created, and entries with a matching `id` are updated in place. - [List eval prompt sets](https://docs.omni.co/api/ai-eval/list-eval-prompt-sets.md): List eval prompt sets, sorted alphabetically by name. When `model_ids` is omitted, returns prompt sets for every shared model the caller can access. Requires at least the Querier role on each requested model. - [Get an eval prompt set](https://docs.omni.co/api/ai-eval/get-an-eval-prompt-set.md): Get a single prompt set with all of its prompts. - [Archive an eval prompt set](https://docs.omni.co/api/ai-eval/archive-an-eval-prompt-set.md): Archive (soft-delete) a prompt set. Omni also attempts to cancel every in-flight agentic job associated with the set; the returned `cancelled_job_count` reports how many were cancelled. Cancellation is best-effort — the archive is committed first, so if a run-cancellation later fails the endpoint re… - [Restore an archived eval prompt set](https://docs.omni.co/api/ai-eval/restore-an-archived-eval-prompt-set.md): Restore an archived prompt set. - [Start an eval run](https://docs.omni.co/api/ai-eval/start-an-eval-run.md): Create and start a new run against an existing prompt set. The run enqueues one agentic job per prompt and begins executing immediately. Returns the newly created run with its initial per-prompt result rows. - [List eval runs](https://docs.omni.co/api/ai-eval/list-eval-runs.md): List runs for a prompt set, newest first, filtered to runs whose model the caller can access. The `prompt_set_id` query parameter is required. - [Get an eval run](https://docs.omni.co/api/ai-eval/get-an-eval-run.md): Get an eval run with every per-prompt result row, including the underlying agentic job state and any scoring data. - [Cancel an eval run](https://docs.omni.co/api/ai-eval/cancel-an-eval-run.md): Cancel an in-flight eval run. Marks the run cancelled first so no in-progress per-prompt job can flip it back to COMPLETE, then cancels every non-terminal agentic job associated with the run. The run is also archived as part of the cancel — the response returns the updated run inline (`status: CANCE… - [Restore an archived eval run](https://docs.omni.co/api/ai-eval/restore-an-archived-eval-run.md): Restore an archived eval run. - [Archive an eval run](https://docs.omni.co/api/ai-eval/archive-an-eval-run.md): Archive (soft-delete) an eval run. Any non-terminal per-prompt agentic jobs are cancelled as part of the archive (best-effort), and a still-RUNNING run is flipped to CANCELLED before archival. The call is idempotent; archiving an already-terminal or already-archived run is a no-op. #### Model Suggestions - [Generate model suggestions](https://docs.omni.co/api/ai-model-suggestions/generate-model-suggestions.md): This endpoint requires **Organization Admin** permissions. - [List AI-generated suggestions](https://docs.omni.co/api/ai-model-suggestions/list-ai-generated-suggestions.md): This endpoint requires **Organization Admin** permissions. - [Dismiss a suggestion](https://docs.omni.co/api/ai-model-suggestions/dismiss-a-suggestion.md): This endpoint requires **Organization Admin** permissions. - [Restore a dismissed suggestion](https://docs.omni.co/api/ai-model-suggestions/restore-a-dismissed-suggestion.md): This endpoint requires **Organization Admin** permissions. - [Delete a suggestion](https://docs.omni.co/api/ai-model-suggestions/delete-a-suggestion.md): **Organization Admin** permissions are required to use this endpoint. - [Get the latest generation run](https://docs.omni.co/api/ai-model-suggestions/get-the-latest-generation-run.md): **Organization Admin** permissions are required to use this endpoint. - [Get status for a generation run](https://docs.omni.co/api/ai-model-suggestions/get-status-for-a-generation-run.md): **Organization Admin** permissions are required to use this endpoint. - [Enable model AI suggestions schedule](https://docs.omni.co/api/ai-model-suggestions/enable-model-ai-suggestions-schedule.md): This endpoint requires **Organization Admin** permissions. - [Disable model AI suggestions schedule](https://docs.omni.co/api/ai-model-suggestions/disable-model-ai-suggestions-schedule.md): This endpoint requires **Organization Admin** permissions. #### Queries and jobs - [Generate a query](https://docs.omni.co/api/ai/generate-a-query.md): Generate a structured Omni query from natural language using AI. - [Pick topic](https://docs.omni.co/api/ai/pick-topic.md): Analyze a natural language prompt and determines which topic in the model is the best fit for answering the question. - [Create AI job](https://docs.omni.co/api/ai/create-ai-job.md): Submit a new AI job for asynchronous execution. The AI will analyze the prompt, generate and execute queries against the specified model, and produce a summarized answer. - [Get AI job status](https://docs.omni.co/api/ai/get-ai-job-status.md): Retrieve the current status and details of an AI job, including its state, progress information, and result summary. - [Cancel AI job](https://docs.omni.co/api/ai/cancel-ai-job.md): Request cancellation of an AI job. This endpoint is idempotent — calling it on an already-cancelled or completed job returns success with the current state. - [Stream AI job results](https://docs.omni.co/api/ai/stream-ai-job-results.md): Retrieve the full result of a completed AI job, including all actions taken by the AI (queries generated, data retrieved) and the final summarized answer. #### Routines - [Create an AI Routine](https://docs.omni.co/api/ai-routines/create-an-ai-routine.md): Create a new AI Routine that will run on the specified schedule. - [Update an AI Routine](https://docs.omni.co/api/ai-routines/update-an-ai-routine.md): Update an existing AI Routine. All request fields are optional, and only supplied fields are changed. Supplying `destination` replaces the full recipient configuration. - [List AI Routines](https://docs.omni.co/api/ai-routines/list-ai-routines.md): List AI Routines for the calling user, newest first. Includes routines paused by the owner or disabled by Omni, but excludes deleted routines. - [Get an AI Routine](https://docs.omni.co/api/ai-routines/get-an-ai-routine.md): Retrieve details for a specific AI Routine by ID, including the status of its most recent completed run. - [Trigger AI Routine](https://docs.omni.co/api/ai-routines/trigger-ai-routine.md): Run an existing routine immediately, in addition to its schedule — e.g. to get an off-cycle result or verify a routine produces the email you expect. - [Delete an AI Routine](https://docs.omni.co/api/ai-routines/delete-an-ai-routine.md): Delete an AI Routine. This action cannot be undone. ### API token APIs - [Enable or disable API token](https://docs.omni.co/api/api-tokens/enable-or-disable-api-token.md): This endpoint requires **Organization Admin** permissions. - [List API tokens](https://docs.omni.co/api/api-tokens/list-api-tokens.md): This endpoint requires **Organization Admin** permissions. - [Retrieve an API token](https://docs.omni.co/api/api-tokens/retrieve-an-api-token.md): This endpoint requires **Organization Admin** permissions. - [Delete API token](https://docs.omni.co/api/api-tokens/delete-api-token.md): This endpoint requires **Organization Admin** permissions. ### App APIs - [Create/reuse draft and replace app content](https://docs.omni.co/api/apps/createreuse-draft-and-replace-app-content.md): This API is currently in development and may change. - [Replace app content on a draft](https://docs.omni.co/api/apps/replace-app-content-on-a-draft.md): This API is currently in development and may change. - [Read app content](https://docs.omni.co/api/apps/read-app-content.md): This API is currently in development and may change. - [Read app content on main draft](https://docs.omni.co/api/apps/read-app-content-on-main-draft.md): This API is currently in development and may change. - [Read app content on a draft](https://docs.omni.co/api/apps/read-app-content-on-a-draft.md): This API is currently in development and may change. - [Remove app from a draft](https://docs.omni.co/api/apps/remove-app-from-a-draft.md): This API is currently in development and may change. ### Connection APIs - [Create connection](https://docs.omni.co/api/connections/create-connection.md): Creates a new database connection. See the **Parameters** - [Update connection](https://docs.omni.co/api/connections/update-connection.md): Update connection properties including credentials. Credentials are encrypted at rest and never returned in API responses. - [List connections](https://docs.omni.co/api/connections/list-connections.md): Retrieves a list of database connections with optional filtering and sorting - [Get connection](https://docs.omni.co/api/connections/get-connection.md): This endpoint requires **Restricted Querier** permissions or higher. - [Delete connection](https://docs.omni.co/api/connections/delete-connection.md): This endpoint requires **Connection Admin** permissions. #### Connection environments - [Create connection environments](https://docs.omni.co/api/connection-environments/create-connection-environments.md): Creates connection environments by associating environment-specific connections with a base connection - [Update connection environment](https://docs.omni.co/api/connection-environments/update-connection-environment.md): Associates user attribute values with a specific connection environment, which will determine when it is used. - [Delete connection environment](https://docs.omni.co/api/connection-environments/delete-connection-environment.md): Deletes a connection environment by ID. Requires Connection Admin or Organization Admin permissions. #### dbt configuration - [Update dbt configuration](https://docs.omni.co/api/dbt/update-dbt-configuration.md): **Connection Admin** permissions are required to use this endpoint. - [Get dbt configuration](https://docs.omni.co/api/dbt/get-dbt-configuration.md): **Connection Admin** permissions are required to use this endpoint. - [Delete dbt configuration](https://docs.omni.co/api/dbt/delete-dbt-configuration.md): **Connection Admin** permissions are required to use this endpoint. #### dbt environments - [Create dbt environment](https://docs.omni.co/api/dbt/create-dbt-environment.md): Create a new [dbt environment](/integrations/dbt/environments) on the specified connection. A dbt environment allows you to connect Omni to a specific dbt project and manage dbt-related functionality within the connection context. - [Update dbt environment](https://docs.omni.co/api/dbt/update-dbt-environment.md): This endpoint requires **Connection Admin** permissions for the connection. - [List dbt environments](https://docs.omni.co/api/dbt/list-dbt-environments.md): This endpoint requires **Connection Admin** permissions for the connection. - [Delete dbt environment](https://docs.omni.co/api/dbt/delete-dbt-environment.md): This endpoint requires **Connection Admin** permissions for the connection. #### Schema refreshes - [Create schema refresh schedule](https://docs.omni.co/api/schema-refresh-schedules/create-schema-refresh-schedule.md): Create a new schema refresh schedule for the specified connection. Multiple schedules can be created for the same connection. - [Update schema refresh schedule](https://docs.omni.co/api/schema-refresh-schedules/update-schema-refresh-schedule.md): Update the schedule and/or timezone for an existing schema refresh schedule. - [Get job status](https://docs.omni.co/api/jobs/get-job-status.md): Currently, this endpoint only supports schema refresh jobs. Job IDs from other job types will return an error. - [List schema refresh schedules](https://docs.omni.co/api/schema-refresh-schedules/list-schema-refresh-schedules.md): Retrieve all schema refresh schedules configured for the specified connection. Each schedule uses a cron expression and timezone to define when the schema should be refreshed. - [Get schema refresh schedule](https://docs.omni.co/api/schema-refresh-schedules/get-schema-refresh-schedule.md): Retrieve the details of a connection's specific schema refresh schedule. - [Delete schema refresh schedule](https://docs.omni.co/api/schema-refresh-schedules/delete-schema-refresh-schedule.md): Delete a schema refresh schedule. This does not affect other schedules for the same connection. ### Content APIs - [Retrieve content](https://docs.omni.co/api/content/retrieve-content.md): Retrieve paginated list of documents and folders - [Search dashboards](https://docs.omni.co/api/content/search-dashboards.md): Free-text search over the organization's dashboards. - [Export dashboard](https://docs.omni.co/api/content-migration/export-dashboard.md): Export dashboard for migration between Omni instances - [Import dashboard](https://docs.omni.co/api/content-migration/import-dashboard.md): Import dashboard to Omni instance. ### Dashboard APIs #### Downloads - [Initiate dashboard or tile download](https://docs.omni.co/api/dashboard-downloads/initiate-download.md): Start an asynchronous download job for a published dashboard, a dashboard draft, or single tile with support for multiple output formats. After starting a job, poll [Check download status](/api/dashboard-downloads/check-download-status) for completion, then retrieve the file from [Download file](/ap… - [Check download status](https://docs.omni.co/api/dashboard-downloads/check-download-status.md) - [Download file](https://docs.omni.co/api/dashboard-downloads/download-file.md) #### Filters - [Update dashboard filters/controls](https://docs.omni.co/api/dashboard-filters/update-dashboard-filterscontrols.md) - [Get dashboard filters and controls](https://docs.omni.co/api/dashboard-filters/get-dashboard-filters-and-controls.md): Retrieve the filter and control configuration for a dashboard, including IDs, types, current default values, and metadata. ### Document APIs #### Draft and publish - [Create document](https://docs.omni.co/api/documents-v2/create-document.md): Create a brand-new document and publish it. Accepts creation metadata (`modelId`, `name`, and optional `identifier` / `description` / `folderId`) plus the same content slice as the draft patch body, including `queryPresentations`, `controls`, `settings`, and `containers`. - [Create draft and patch document](https://docs.omni.co/api/documents-v2/create-draft-and-patch-document.md): Create a new draft on the published document and apply the patch. There is no auto-publish — the response includes the new `draftIdentifier` for follow-up calls. Pass an optional `branchId` to attach the draft to a branch; omit it for a draft on the main (unpublished) workspace. - [Patch draft](https://docs.omni.co/api/documents-v2/patch-draft.md): Apply a patch to an existing draft. The request body, content sections, field caps, and tile-addressing rules are identical to [Create draft and patch document](/api/documents-v2/create-draft-and-patch-document); this route does not accept `branchId`. - [Publish draft](https://docs.omni.co/api/documents-v2/publish-draft.md): Publish the document's current main (non-branch) draft, promoting it to the published version. No request body — the draft is consumed, so the response echoes the now-published document's metadata. - [Upgrade dashboard layout](https://docs.omni.co/api/documents/upgrade-dashboard-layout.md): Upgrade a document to the advanced dashboard layout — the same action available in the UI under **File > Upgrade layout**. - [Get document state](https://docs.omni.co/api/documents-v2/get-document-state.md): Retrieve the document's published state. The response can be used as-is as the request body in a call to the [Patch draft API](/api/documents-v2/patch-draft). - [List document drafts](https://docs.omni.co/api/documents/list-document-drafts.md): This endpoint requires **Viewer** permissions or higher on the specified document. - [Get draft state](https://docs.omni.co/api/documents-v2/get-draft-state.md): Read the named draft's state. The response can be used as a request body when [creating](/api/documents-v2/create-draft-and-patch-document) and [patching](/api/documents-v2/patch-draft) drafts. - [Archive draft](https://docs.omni.co/api/documents/archive-draft.md): Archive the current draft of the specified document. Archived drafts are placed in the [**Archived** section of the **Drafts** drawer](/content/develop/drafts#archiving-drafts) in the document's workbook and retained for 30 days. - [Remove dashboard from document](https://docs.omni.co/api/documents/remove-dashboard-from-document.md): Remove the dashboard from an existing draft, leaving a workbook-only document. Documents that are already workbook-only will remain unchanged. - [Delete document](https://docs.omni.co/api/documents/delete-document.md): Delete a document (move to Trash) #### Favorites - [Favorite document](https://docs.omni.co/api/document-favorites/favorite-document.md): Add a document to a user's favorites. Only published documents can be favorited. - [List document favoriters](https://docs.omni.co/api/document-favorites/list-document-favoriters.md): This endpoint requires **Manager** or **Owner** permissions on the requested document. - [Unfavorite document](https://docs.omni.co/api/document-favorites/unfavorite-document.md): Remove a document from a user's favorites. Only published documents can be unfavorited. #### Labels - [Bulk update document labels](https://docs.omni.co/api/document-labels/bulk-update-document-labels.md): Add and/or remove multiple labels from a document in a single atomic operation. - [Apply label to document](https://docs.omni.co/api/document-labels/apply-label-to-document.md): Apply an existing label to a document. Labels must be created first via the [Create label](/api/labels/create-label) endpoint. - [Remove label from document](https://docs.omni.co/api/document-labels/remove-label-from-document.md): Remove a label from a document. #### Management - [List documents](https://docs.omni.co/api/documents/list-documents.md): List documents with pagination and filtering - [List document queries](https://docs.omni.co/api/documents/list-document-queries.md): Retrieve queries associated with a document by its identifier. The specified document must be a saved document with at least one query in the workbook. - [Rename document identifier](https://docs.omni.co/api/documents-v2/rename-document-identifier.md): Rename a published document's identifier. The change is applied live and immediately. Changes do not go through the draft/publish workflow. The former identifier is recorded in the document's rename history to enable automatic redirects. Only published documents can be renamed. - [Move document](https://docs.omni.co/api/documents/move-document.md): Move a document to new folder or change scope. - [Duplicate published document](https://docs.omni.co/api/documents/duplicate-published-document.md): Duplicate a published document. - [Transfer document ownership](https://docs.omni.co/api/documents/transfer-document-ownership.md): This endpoint is deprecated. Use the [Grant document permissions](/api/document-permissions/grant-document-permissions) and [Update document permissions](/api/document-permissions/update-document-permissions) endpoints to assign document ownership. #### Permissions - [Grant document permissions](https://docs.omni.co/api/document-permissions/grant-document-permissions.md): Grant document permissions to users or groups. - [Update document permission settings](https://docs.omni.co/api/document-permissions/update-document-permission-settings.md): Update the permission and [interactivity settings](/share#controlling-document-interactivity) for a document. For example, the ability to allow users to schedule or download the document's content. - [Update document permissions](https://docs.omni.co/api/document-permissions/update-document-permissions.md): Update existing document permissions for users or groups. - [List all users and groups with document access](https://docs.omni.co/api/document-permissions/list-all-users-and-groups-with-document-access.md): List all users and groups with access to a document. - [Get document permissions](https://docs.omni.co/api/document-permissions/get-document-permissions.md): Retrieve the document-level ability values (the **Abilities** toggles in the document's settings), plus the resolved permits for a specific user when `userId` is provided. - [Revoke document permissions](https://docs.omni.co/api/document-permissions/revoke-document-permissions.md): Revoke document permissions for users or user groups. #### Deprecated (v1) - [Create document](https://docs.omni.co/api/documents/create-document.md): This endpoint is deprecated. Use the [Documents v2 API](/api/documents-v2/create-document) instead. - [Create draft](https://docs.omni.co/api/documents/create-draft.md): This endpoint is deprecated. Use the [Documents v2 API](/api/documents-v2/create-draft-and-patch-document) instead. - [Get dashboard document](https://docs.omni.co/api/documents/get-dashboard-document.md): This endpoint is deprecated. Use the [Documents v2 API](/api/documents-v2/get-document-state) instead. ### Folder APIs - [List folders](https://docs.omni.co/api/folders/list-folders.md): Retrieve a paginated list of folders within an organization. Supports filtering, sorting, and cursor-based pagination. - [Create folder](https://docs.omni.co/api/folders/create-folder.md): Create a new folder. Folders can be nested up to 7 levels. - [Update folder](https://docs.omni.co/api/folders/update-folder.md): This endpoint requires [**Editor** permissions or higher](/share#content-access-permissions) on the folder being updated. - [Delete folder](https://docs.omni.co/api/folders/delete-folder.md): Delete a folder. By default, only empty folders can be deleted. Use the `force` parameter to recursively delete folders containing documents and sub-folders. #### Labels - [Bulk update folder labels](https://docs.omni.co/api/folder-labels/bulk-update-folder-labels.md): Add and/or remove multiple labels from a folder. #### Permissions - [Grant folder permissions](https://docs.omni.co/api/folder-permissions/grant-folder-permissions.md): Grant folder permissions to users or groups - [Update organization-level folder permissions](https://docs.omni.co/api/folder-permissions/update-organization-level-folder-permissions.md): Set the role every member of the organization holds on a folder, and/or turn [AccessBoost](/share#boosting-permissions-with-accessboost) on or off for that organization-wide access, without naming individual users or groups. The role cascades to every descendant folder and document, so a single call… - [Update folder permissions](https://docs.omni.co/api/folder-permissions/update-folder-permissions.md): Update existing folder permissions for users or groups - [Get folder permissions](https://docs.omni.co/api/folder-permissions/get-folder-permissions.md): Retrieve folder permissions for a user - [Revoke folder permissions](https://docs.omni.co/api/folder-permissions/revoke-folder-permissions.md): Revoke folder permissions from users or groups ### Label APIs - [Create label](https://docs.omni.co/api/labels/create-label.md): Create a new label in the organization. - [Update label](https://docs.omni.co/api/labels/update-label.md): Update an existing label, including renaming, changing **Verified** status, or adding/removing it from the **Homepage**. - [List labels](https://docs.omni.co/api/labels/list-labels.md): Retrieve all labels in the organization. - [Get label](https://docs.omni.co/api/labels/get-label.md): Retrieve a single label by name. - [Delete label](https://docs.omni.co/api/labels/delete-label.md): Delete a label from the organization. ### Model APIs - [Create model](https://docs.omni.co/api/models/create-model.md): Create a new model. The typical workflow for using this endpoint is: - [Rename model](https://docs.omni.co/api/models/rename-model.md): **Connection Admin** permissions are required to rename a shared model or shared extension model. **Modeler** permissions and higher are required to rename a branch model. - [Archive shared or extension model](https://docs.omni.co/api/models/archive-shared-or-extension-model.md): **Connection Admin** permissions are required to use this endpoint. - [Refresh schema](https://docs.omni.co/api/models/refresh-schema.md): This endpoint requires either **Connection Admin** or **Modeler** permissions: - [List models](https://docs.omni.co/api/models/list-models.md): Retrieves a paginated list of models with their metadata. - [Validate model](https://docs.omni.co/api/models/validate-model.md): Retrieve validation issues for a model and its branches. #### Branches - [Merge a branch](https://docs.omni.co/api/model-branches/merge-a-branch.md): Merge a model branch into the shared model. - [Set dbt environment on model branch](https://docs.omni.co/api/dbt/set-dbt-environment-on-model-branch.md): Sets the active dbt environment on a model branch. This endpoint allows you to programmatically configure which dbt environment a branch should use, enabling CI/CD pipelines to automate dbt environment configuration before triggering schema refreshes. - [Delete branch](https://docs.omni.co/api/models/delete-branch.md): Deletes a branch associated with the specified shared model. #### Content validator - [Validate content](https://docs.omni.co/api/content-validator/validate-content.md): Validate all content against the model and return documents with queries and any validation issues. - [Find and replace content](https://docs.omni.co/api/content-validator/find-and-replace-content.md): Performs find/replace operations on content using the specified model. #### Management - [Get model AI agent actions](https://docs.omni.co/api/models/get-model-ai-agent-actions.md): Return AI agent actions configured for a model — a unified list of sample queries and skills suitable for surfacing as suggested prompts in AI interfaces. - [Reset cache](https://docs.omni.co/api/models/reset-cache.md): Reset the cache for the specified cache policy. - [List model schemas](https://docs.omni.co/api/models/list-model-schemas.md): Retrieves a sorted list of all available schema names for the specified model, including physical, virtual, and dynamic schemas. - [Get dbt exposures](https://docs.omni.co/api/dbt/get-dbt-exposures.md): **Connection Admin** permissions are required to use this endpoint. #### Git - [Get Git configuration](https://docs.omni.co/api/model-git-configuration/get-git-configuration.md): Retrieve the Git configuration for a shared model. - [Create Git configuration](https://docs.omni.co/api/model-git-configuration/create-git-configuration.md): Create a new Git configuration for a shared model. - [Update Git configuration](https://docs.omni.co/api/model-git-configuration/update-git-configuration.md): Update the Git configuration for a shared model. Oly provided fields will be updated. - [Delete Git configuration](https://docs.omni.co/api/model-git-configuration/delete-git-configuration.md): Remove the Git configuration from a shared model. - [Sync model with Git repository](https://docs.omni.co/api/model-git-configuration/sync-model-with-git-repository.md): Trigger a sync operation between the model and its configured Git repository. - [Create or update a pull request for a model branch](https://docs.omni.co/api/model-git-configuration/create-or-update-a-pull-request-for-a-model-branch.md): This endpoint requires **Modeler** or **Connection Admin** permisisons. - [Migrate a model](https://docs.omni.co/api/models/migrate-a-model.md): Copy a model from one Omni connection to another by reading the source model's YAML at a specific Git ref and writing it to the target model. Supports same-organization and cross-organization migrations. #### Topics - [Retrieve a topic](https://docs.omni.co/api/topics/retrieve-a-topic.md): Retrieve a topic in a model by name. #### Views - [Delete view](https://docs.omni.co/api/models/delete-view.md): Delete or ignores a view in a model. Use the `mode` parameter to specify the behavior of this endpoint. #### YAML files - [Create or update YAML files](https://docs.omni.co/api/models/create-or-update-yaml-files.md): Create or overwrite a YAML file for a model. The file can be a special file (`model` or `relationships`) or a YAML file ending in `.topic`, `.view`, or `.composite_topic`. - [Get model YAML](https://docs.omni.co/api/models/get-model-yaml.md): Retrieve the YAML representation of a model with optional filtering and mode selection. - [Delete a YAML file](https://docs.omni.co/api/models/delete-a-yaml-file.md): Delete a topic, composite topic, or view YAML file from a model. The file must be a YAML file ending in `.topic`, `.composite_topic`, or `.view`. ### Query APIs - [Run query](https://docs.omni.co/api/queries/run-query.md): Run the query specified in the request body. Successful requests will return the data as a base64 encoded [Apache Arrow](https://arrow.apache.org/) table, allowing you to extract query results from Omni and use them elsewhere. For example, piping data to Google Sheets or leveraging data in a Python… - [Wait for query results](https://docs.omni.co/api/queries/wait-for-query-results.md): Poll for the results of one or more query jobs. Use this endpoint when a request to the [Run query endpoint](/api/queries/run-query) times out and returns `remaining_job_ids` in the response. ### Schedule APIs - [Create schedule](https://docs.omni.co/api/schedules/create-schedule.md): Create a scheduled task for the specified dashboard. Supports applying filters and formatting, creating alert conditions, and triggering test deliveries. - [Update schedule](https://docs.omni.co/api/schedules/update-schedule.md): Update the specified task. Changes to the schedule are applied to future runs. Currently running jobs are not affected. - [Transfer schedule ownership](https://docs.omni.co/api/schedules/transfer-schedule-ownership.md): Transfer ownership of a schedule from one user to another user in the same organization. New ownership will be immediate and can't be reversed using this endpoint. - [List schedules](https://docs.omni.co/api/schedules/list-schedules.md): Retrieves scheduled tasks. This endpoint supports filtering, sorting, and cursor-based pagination. - [Get schedule](https://docs.omni.co/api/schedules/get-schedule.md): Retrieve the details of a single schedule, including its delivery destinations, recurrence configuration, and current status. - [Delete schedule](https://docs.omni.co/api/schedules/delete-schedule.md): Delete a schedule. #### Runs - [Trigger schedule](https://docs.omni.co/api/schedules/trigger-schedule.md): Trigger the execution of a schedule on demand, outside of its regular schedule. - [Pause schedule](https://docs.omni.co/api/schedules/pause-schedule.md): Pause a schedule. - [Resume schedule](https://docs.omni.co/api/schedules/resume-schedule.md): Resume a schedule. #### Recipients - [Add schedule recipients](https://docs.omni.co/api/schedule-recipients/add-schedule-recipients.md): Add one or more recipients to an existing scheduled email task. Recipients can be specified by email address or user ID. - [Remove schedule recipients](https://docs.omni.co/api/schedule-recipients/remove-schedule-recipients.md): Remove one or more recipients from an existing scheduled email task. Recipients can be specified by email address or user ID. - [Manage email-only user](https://docs.omni.co/api/schedule-recipients/manage-email-only-user.md): Create or update an [email-only user](/share/deliveries/email). An email-only user is a recipient of a delivery that isn't associated with an Omni account. - [Bulk manage email-only users](https://docs.omni.co/api/schedule-recipients/bulk-manage-email-only-users.md): Create or update up to 20 [email-only users](/share/deliveries/email). An email-only user is a recipient of a delivery that isn't associated with an Omni account. - [List schedule recipients](https://docs.omni.co/api/schedule-recipients/list-schedule-recipients.md): Retrieve the list of recipients for the specified schedule. Successful responses will include the recipients and details about the schedule's destination type. ### Upload APIs - [Upload a CSV file](https://docs.omni.co/api/uploads/upload-a-csv-file.md): To use this endpoint: - The **Upload data** setting in **Settings > Content permissions** must enabled by an **Organization Admin** - The authenticating user must have **Restricted Querier** permissions or higher on the model the file will be uploaded to - [Replace upload data](https://docs.omni.co/api/uploads/replace-upload-data.md): **Organization Admin** permissions are required to use this endpoint. - [List uploads](https://docs.omni.co/api/uploads/list-uploads.md): List all uploads ([CSV files and spreadsheets](/analyze-explore/data-input-csvs)) in the organization with metadata and optional filtering. - [Delete an upload](https://docs.omni.co/api/uploads/delete-an-upload.md): Delete a CSV upload by its ID. This removes the file from storage and marks the record as deleted. ### User APIs - [Create user](https://docs.omni.co/api/users/create-user.md): Create a user. - [Replace user](https://docs.omni.co/api/users/replace-user.md): Replace the specified user. Per the SCIM 2.0 specification, `PUT` replaces the entire user resource: any optional attribute omitted from the request body is reset to its default value. - [Update user](https://docs.omni.co/api/users/update-user.md): Update the specified user by applying a list of [SCIM 2.0 patch operations](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2). Attributes not referenced in the request are left unchanged. - [Retrieve user](https://docs.omni.co/api/users/retrieve-user.md): Retrieve a user using their unique ID. - [List users](https://docs.omni.co/api/users/list-users.md): List users in the organization, sorted by creation time. Use the [embed users](/api/users/list-embed-users) endpoint to retrieve embed users. - [Delete user](https://docs.omni.co/api/users/delete-user.md): Delete the specified user. Use the [Delete embed user](/api/users/delete-embed-user) endpoint to delete embed users. #### Email-only users - [List email-only users](https://docs.omni.co/api/users/list-email-only-users.md): List email-only users and their user attributes. Supports pagination and filtering. #### Embed users - [List embed users](https://docs.omni.co/api/users/list-embed-users.md): List embed users in the organization, sorted by creation time. Use the [users](/api/users/list-users) endpoint to retrieve standard users. - [Retrieve embed user](https://docs.omni.co/api/users/retrieve-embed-user.md): Retrieve an embed user using their unique ID. Use the [Retrieve user](/api/users/retrieve-user) endpoint to retrieve standard users. - [Delete embed user](https://docs.omni.co/api/users/delete-embed-user.md): Delete the specified embed user. Use the [Delete user](/api/users/delete-user) endpoint to delete standard users. #### Model roles - [Assign or update user model role](https://docs.omni.co/api/user-model-roles/assign-or-update-user-model-role.md): Assign or update a model role for a user. If the user already has a role for the specified model, this endpoint will update it to the new role. - [Retrieve user model roles](https://docs.omni.co/api/user-model-roles/retrieve-user-model-roles.md): Retrieve the model role assignments for a user. This includes both direct role assignments and roles inherited from user group memberships. #### User attributes - [List user attributes](https://docs.omni.co/api/user-attributes/list-user-attributes.md): **Organization Admin** permissions are required to use this endpoint. ### User group APIs - [Create user group](https://docs.omni.co/api/user-groups/create-user-group.md): Create a [user group](/administration/users/groups). To manage model and connection role assignments for user groups, see the [User group model role APIs](/api/user-group-model-roles). - [Replace user group](https://docs.omni.co/api/user-groups/replace-user-group.md): Replace the specified user group. Per the SCIM 2.0 specification, `PUT` replaces the entire group resource, including its membership. - [Update user group](https://docs.omni.co/api/user-groups/update-user-group.md): Update the specified user group by applying a list of [SCIM 2.0 patch operations](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2). Use `PATCH` to add or remove individual members, or to rename the group, without affecting other attributes. - [List user groups](https://docs.omni.co/api/user-groups/list-user-groups.md): Return a list of user groups, sorted by creation time. - [Retrieve user group](https://docs.omni.co/api/user-groups/retrieve-user-group.md): Retrieves a user group using its unique ID. - [Delete user group](https://docs.omni.co/api/user-groups/delete-user-group.md): Delete the specified user group. #### Model roles - [Assign or update user group model role](https://docs.omni.co/api/user-group-model-roles/assign-or-update-user-group-model-role.md): Assign or update a model role for a user group. If the user group already has a role for the specified model, this endpoint will update it to the new role. All members of the user group will inherit this role. - [Retrieve user group model roles](https://docs.omni.co/api/user-group-model-roles/retrieve-user-group-model-roles.md): Retrieve the model role assignments for a user group. ## OpenAPI Specs - [openapi](/api/openapi.yaml)