# 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, which routes they apply to, and how to handle them in your integration. - [Omni API errors and retries](https://docs.omni.co/api/errors.md): Understand the error responses the Omni API returns, including during scheduled maintenance, and which ones are safe to retry. - [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. ### Administration APIs #### API keys - [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. #### IP allowlist - [Get the IP allowlist](https://docs.omni.co/api/ip-allowlist/get-the-ip-allowlist.md): **Organization Admin** permissions are required for this endpoint. - [Update the IP allowlist](https://docs.omni.co/api/ip-allowlist/update-the-ip-allowlist.md): **Organization Admin** permissions are required for this endpoint. #### Color palettes - [Create custom color palette](https://docs.omni.co/api/color-palettes/create-custom-color-palette.md): This endpoint requires **Organization Admin** permissions. - [Update custom color palette](https://docs.omni.co/api/color-palettes/update-custom-color-palette.md): This endpoint requires **Organization Admin** permissions. - [List custom color palettes](https://docs.omni.co/api/color-palettes/list-custom-color-palettes.md): List the custom chart color palettes defined for the organization. Built-in palettes are not included. - [Get custom color palette](https://docs.omni.co/api/color-palettes/get-custom-color-palette.md): Retrieve a custom chart color palette by ID. - [Delete custom color palette](https://docs.omni.co/api/color-palettes/delete-custom-color-palette.md): This endpoint requires **Organization Admin** permissions. ### 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. `userId` identifies who the conversation belongs to, whether it started in the Omni UI or through the API. #### 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. - [Set individual user groups' AI credit limits](https://docs.omni.co/api/ai-credit-controls/set-individual-user-groups-ai-credit-limits.md): **Organization Admin** permissions are required to use this endpoint. - [List individual user groups' AI credit limits](https://docs.omni.co/api/ai-credit-controls/list-individual-user-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. - [Read individual user groups' AI credit usage](https://docs.omni.co/api/ai-credit-usage/read-individual-user-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. - [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. - [List available LLMs](https://docs.omni.co/api/ai/list-available-llms.md): List the LLMs the caller may pass as `requestedLlm` on the [Create AI job](/api/ai/create-ai-job) and [Generate a query](/api/ai/generate-a-query) endpoints. - [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. - [Rate an AI job's response](https://docs.omni.co/api/ai/rate-an-ai-jobs-response.md): Rate an AI job's response using the same thumbs up/thumbs down and optional comment a user can give a response in the Omni UI or in Slack. - [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. - [Render AI job visualization](https://docs.omni.co/api/ai/render-ai-job-visualization.md): Render the visualization from a completed AI job as a PNG image. #### Routines - [Create an AI Routine](https://docs.omni.co/api/ai-routines/create-an-ai-routine.md): Create a new AI Routine that runs a saved prompt on a schedule and delivers the AI response through email, Slack, or a webhook. To run a routine when a condition is met, provide a `condition` in the request body. - [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 — switching to a different destination type (email, Slack, or webhook) clears the previous destination's state, such as a linked Sla… - [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 its persisted condition query and 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. The routine will immediately stop running. This action cannot be undone. #### Skills - [Create a skill](https://docs.omni.co/api/skills/create-a-skill.md): This endpoint is currently in development and may change. - [Edit a skill](https://docs.omni.co/api/skills/edit-a-skill.md): This endpoint is currently in development and may change. - [List skills](https://docs.omni.co/api/skills/list-skills.md): This endpoint is currently in development and may change. - [Get a skill](https://docs.omni.co/api/skills/get-a-skill.md): This endpoint is currently in development and may change. - [Delete a skill](https://docs.omni.co/api/skills/delete-a-skill.md): This endpoint is currently in development and may change. ### 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. - [Create/reuse draft and edit app content](https://docs.omni.co/api/apps/createreuse-draft-and-edit-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. - [Edit app content on a draft](https://docs.omni.co/api/apps/edit-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. #### Downloads - [Initiate app download](https://docs.omni.co/api/app-downloads/initiate-app-download.md): Start an asynchronous download job for a published app, rendered headlessly the same way a scheduled app delivery renders it. Every query in the app's workbook runs, including linked tabs; queries on a model the downloading user cannot query are omitted. Only the app's default view is rendered. - [Get app download status](https://docs.omni.co/api/app-downloads/get-app-download-status.md): Poll the status of an app download job started by [Initiate app download](/api/app-downloads/initiate-app-download). Poll until `status` is `complete`, then fetch the file from [Get app download file](/api/app-downloads/get-app-download-file). - [Get app download file](https://docs.omni.co/api/app-downloads/get-app-download-file.md): Stream the finished file for an app download job. Poll [Get app download status](/api/app-downloads/get-app-download-status) until `status` is `complete` first. Finished files are retained for about a day. ### Branch APIs - [List branches](https://docs.omni.co/api/branches/list-branches.md): List the branches the caller may see: - [Get a branch](https://docs.omni.co/api/branches/get-a-branch.md): Get a branch and its parts, as the caller sees them. Each branch part includes whether the caller may merge it, and a reason code when they may not. The response only includes branch parts that the caller can see. - [Open or close a branch to viewers](https://docs.omni.co/api/branches/open-or-close-a-branch-to-viewers.md): Opening a branch with this endpoint requires permission to edit every model in the branch. Closing a branch only requires permission to edit the branch on one of its member models. ### 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): The permissions required depend on who owns the environment: - [List dbt environments](https://docs.omni.co/api/dbt/list-dbt-environments.md): This endpoint requires **Restricted Querier** permissions or higher on the connection. - [Delete dbt environment](https://docs.omni.co/api/dbt/delete-dbt-environment.md): The permissions required depend on who owns the environment: #### 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 and apps](https://docs.omni.co/api/content/search-dashboards-and-apps.md): Free-text search over the organization's dashboards and apps. Apps are included only if they are enabled for the organization. - [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): This API is in beta and may have future breaking changes. ### 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): Retrieve the current status of a dashboard or tile download job. Poll this endpoint to determine when the file is ready. - [Download file](https://docs.omni.co/api/dashboard-downloads/download-file.md): Retrieve the completed dashboard or tile download file.Only call this endpoint when the [Check download status endpoint](/api/dashboard-downloads/check-download-status) returns a `complete` status. #### 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): This endpoint is deprecated. Use [Get document](/api/documents-v2/get-document-state) to read a published dashboard's filters and controls from `controls`, or [Get draft](/api/documents-v2/get-draft-state) to read them from a draft. ### Document APIs #### Draft and publish - [Create and publish document](https://docs.omni.co/api/documents-v2/create-document.md): Create and publish a brand-new document. - [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. The response includes `draftOf.identifier`, the published document this draft belongs to. - [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. - [Run a saved document query](https://docs.omni.co/api/documents/run-a-saved-document-query.md): Run one of a document's saved queries and returns the results as JSON, CSV, or XLSX. Only adding and updating existing filters is supported. To modify more than a query's filters before running it, see the [Running document queries with APIs guide](/guides/api/run-document-queries). - [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. ### Embed APIs - [Generate embedded SSO session](https://docs.omni.co/api/embed/generate-embedded-sso-session.md): The [Embed](/embed) feature must be enabled in your Omni organization to use this endpoint. ### Folder APIs - [Create folder](https://docs.omni.co/api/folders/create-folder.md): Create a new folder. Folders can be nested up to 7 levels. - [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. - [Get folder](https://docs.omni.co/api/folders/get-folder.md): Retrieve a single folder by its ID. Owner and permission information is returned separately by the [Get folder permissions](/api/folder-permissions/get-folder-permissions) endpoint. - [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. #### Favorites - [Favorite folder](https://docs.omni.co/api/folder-favorites/favorite-folder.md): Add a folder to a user's favorites. Permissions are not checked; note that favoriting a folder using this endpoint does not grant access. - [Unfavorite folder](https://docs.omni.co/api/folder-favorites/unfavorite-folder.md): Remove a folder from a user's favorites. #### 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 the permissions on a folder. - [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. - [Re-parse model SQL](https://docs.omni.co/api/models/re-parse-model-sql.md): **Querier** permissions or higher on a model are required to use this endpoint. - [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, or a shared extension model in the **Develop independently** branch workflow that owns its own Git repository, separate from its parent model's. - [Create Git configuration](https://docs.omni.co/api/model-git-configuration/create-git-configuration.md): Create a new Git configuration for a shared model, or a shared extension model in the **Develop independently** branch workflow. A shared extension's Git configuration is its own, separate from its parent model's. - [Update Git configuration](https://docs.omni.co/api/model-git-configuration/update-git-configuration.md): Update the Git configuration for a shared model, or a shared extension model in the **Develop independently** branch workflow. Only 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, or a shared extension model in the **Develop independently** branch workflow. - [Sync model with Git repository](https://docs.omni.co/api/model-git-configuration/sync-model-with-git-repository.md): Trigger a sync between the model and its configured Git repository. Omni pulls the latest changes from the repository and, if the model has changes not yet in Git, pushes them in a commit using `commitMessage`. - [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** permissions. - [Rotate webhook secret](https://docs.omni.co/api/model-git-configuration/rotate-webhook-secret.md): This endpoint requires Modeler permissions or higher. - [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 - [Update topic](https://docs.omni.co/api/topics/update-topic.md): Update an existing topic. - [List topics](https://docs.omni.co/api/topics/list-topics.md): Retrieve a list of topics in the model, including composite topics. - [Retrieve a topic](https://docs.omni.co/api/topics/retrieve-a-topic.md): Retrieve a topic in a model by name. - [Delete topic](https://docs.omni.co/api/topics/delete-topic.md): Delete a topic from a model. #### 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. - [Update field metadata](https://docs.omni.co/api/models/update-field-metadata.md): Update a field's metadata on a view. Omitted properties keep their current value. #### 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 semantic query specified in the request body. Successful requests will return the results according to the specified [`resultType`](#results). - [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. - [Read query results by offset](https://docs.omni.co/api/queries/read-query-results-by-offset.md): Read a completed job's stored result by raw byte offset. See [Reading large results](/api/queries/run-query#reading-large-results) for the full flow with `completionOnly`. ### Schedule APIs - [Create schedule](https://docs.omni.co/api/schedules/create-schedule.md): Create a scheduled task delivering a document's dashboard, or one tab of its workbook with `entity: workbook`. 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, whether it delivers a dashboard or a tab of a workbook. 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. A schedule can deliver a dashboard or a workbook. - [Delete schedule](https://docs.omni.co/api/schedules/delete-schedule.md): Move a schedule to the trash. It stops running and can be restored with the [Restore schedule](/api/schedules/restore-schedule) endpoint. - [Restore schedule](https://docs.omni.co/api/schedules/restore-schedule.md): Restore a schedule out of the trash. It runs on its schedule again, unless it was paused before it was deleted or Omni disabled it. For example, because its Slack or Google Sheets account was disconnected. #### 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, user ID, or user group 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, user ID, or user group ID. - [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 - [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 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. - [Bulk delete email-only users](https://docs.omni.co/api/schedule-recipients/bulk-delete-email-only-users.md): Delete up to 100 [email-only users](/administration/users/email-only) in a single request, identified by ID, by email, or a mix of both. Deleting an email-only user also removes them as a recipient from every schedule they receive. #### 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 - [Create user attribute](https://docs.omni.co/api/user-attributes/create-user-attribute.md): **Organization Admin** permissions are required to use this endpoint. - [Update a user attribute definition](https://docs.omni.co/api/user-attributes/update-a-user-attribute-definition.md): **Organization Admin** permissions are required to use this endpoint. - [List user attributes](https://docs.omni.co/api/user-attributes/list-user-attributes.md): **Organization Admin** permissions are required to use this endpoint. - [Delete a user attribute definition](https://docs.omni.co/api/user-attributes/delete-a-user-attribute-definition.md): **Organization Admin** permissions are required to use this endpoint. - [Set switchable values for a user or group](https://docs.omni.co/api/user-attributes/set-switchable-values-for-a-user-or-group.md): **Organization Admin** permissions are required to use this endpoint. - [Retrieve switchable values for a user or group](https://docs.omni.co/api/user-attributes/retrieve-switchable-values-for-a-user-or-group.md): **Organization Admin** permissions are required to use this endpoint. - [Switch an attribute value for the current user](https://docs.omni.co/api/user-attributes/switch-an-attribute-value-for-the-current-user.md): Switches a user attribute value for the calling user. The switch then drives dynamic shared extensions, access filters and connection environment routing exactly as an assigned value would. - [List switchable attributes for the current user](https://docs.omni.co/api/user-attributes/list-switchable-attributes-for-the-current-user.md): Retrieve the [user attributes](/administration/users/attributes/user-selected) the calling user can switch, along with any switch that is currently active. - [Clear a switched attribute value for the current user](https://docs.omni.co/api/user-attributes/clear-a-switched-attribute-value-for-the-current-user.md): Clear the calling user's switch for a [user attribute](/administration/users/attributes/user-selected), restoring the administrator-assigned value. Clearing an attribute that is not currently switched succeeds and changes nothing. ### 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)