Who am I?
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/whoami | Retrieve the authenticated caller’s own identity, API key scope, organization role, and resolved per-model permissions. Supports filtering to specific models. | v1 (latest) |
AI
Branding
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/ai/branding | Return the organization’s AI Agent’s branding configuration, including display name, custom logo URL, and copy for AI Agent landing surfaces. | v1 (latest) |
Conversations
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/ai/conversations | List a user’s recent AI conversations, ordered by most-recent activity. | v1 (latest) |
| GET /v1/ai/conversations/:conversationId | Retrieve a conversation with its full message history — alternating user and assistant turns. | v1 (latest) |
Credit Controls
| Endpoint | Description | Version + Status |
|---|---|---|
| PATCH /v1/ai/credit-controls/users | Set individual users’ AI credit limits in bulk. | v1 (latest) |
| PATCH /v1/ai/credit-controls | Update the organization’s AI credit controls. | v1 (latest) |
| GET /v1/ai/credit-controls | Get the organization’s current AI credit control settings, usage for the current billing period, and the billing period bounds. | v1 (latest) |
| GET /v1/ai/credit-controls/users | List the organization’s active individual user AI credit limits, ordered by userId ascending. | v1 (latest) |
Evals
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/ai/eval/prompt-sets | Create a new eval prompt set bound to a shared model. | v1 (latest) |
| PATCH /v1/ai/eval/prompt-sets/:promptSetId | Update a prompt set’s name, description, and/or prompts. | v1 (latest) |
| GET /v1/ai/eval/prompt-sets | List eval prompt sets, sorted alphabetically by name. | v1 (latest) |
| GET /v1/ai/eval/prompt-sets/:promptSetId | Get a single prompt set with all of its prompts. | v1 (latest) |
| DELETE /v1/ai/eval/prompt-sets/:promptSetId | Archive (soft-delete) a prompt set. | v1 (latest) |
| POST /v1/ai/eval/prompt-sets/:promptSetId/unarchive | Restore an archived prompt set. | v1 (latest) |
| POST /v1/ai/eval/runs | Create and start a new run against an existing prompt set. | v1 (latest) |
| GET /v1/ai/eval/runs | List runs for a prompt set, newest first, filtered to runs whose model the caller can access. | v1 (latest) |
| GET /v1/ai/eval/runs/:runId | Get an eval run with every per-prompt result row, including the underlying agentic job state and any scoring data. | v1 (latest) |
| POST /v1/ai/eval/runs/:runId/cancel | Cancel an in-progress eval run. | v1 (latest) |
| POST /v1/ai/eval/runs/:runId/unarchive | Restore an archived eval run. | v1 (latest) |
| DELETE /v1/ai/eval/runs/:runId | Archive (soft-delete) an eval run. | v1 (latest) |
Model Suggestions
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/models/:modelId/suggestions/generate | Trigger an AI suggestion generation run for the shared model and enqueue the async job. | v1 (latest) |
| GET /v1/models/:modelId/suggestions | List AI-generated suggestions for a shared model. | v1 (latest) |
| POST /v1/models/:modelId/suggestions/:suggestionId/ignore | Dismiss a suggestion, removing it from the active list. | v1 (latest) |
| POST /v1/models/:modelId/suggestions/:suggestionId/restore | Restore a previously dismissed suggestion back to the active list. | v1 (latest) |
| DELETE /v1/models/:modelId/suggestions/:suggestionId | Permanently delete a suggestion. | v1 (latest) |
| GET /v1/models/:modelId/suggestions/runs/latest | Retrieve the most recent generation run for the shared model. | v1 (latest) |
| GET /v1/models/:modelId/suggestions/runs/:runId | Retrieve the status of a specific generation run. | v1 (latest) |
| PUT /v1/models/:modelId/suggestions/schedule | Enable the daily generation schedule for AI model suggestions on a shared model. | v1 (latest) |
| DELETE /v1/models/:modelId/suggestions/schedule | Disable the daily generation schedule for AI model suggestions on a shared model. | v1 (latest) |
Queries and jobs
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/ai/generate-query | Generate a structured Omni query from natural language using AI. | v1 (latest) |
| POST /v1/ai/pick-topic | Analyze a natural language prompt and determine which topic in the model is the best fit for answering the question. | v1 (latest) |
| POST /v1/ai/jobs | Submit a new AI job for asynchronous execution. | v1 (latest) |
| GET /v1/ai/jobs/:jobId | Retrieve the current status and details of an AI job, including its state, progress information, and result summary. | v1 (latest) |
| POST /v1/ai/jobs/:jobId/cancel | Request cancellation of an AI job. | v1 (latest) |
| GET /v1/ai/jobs/:jobId/result | Retrieve the full result of a completed AI job, including all actions taken by the AI and the final summarized answer. | v1 (latest) |
Routines
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/ai/routines | Create a new routine that will run on the specified schedule. | v1 (latest) |
| PUT /v1/ai/routines/:routineId | Update an existing routine. | v1 (latest) |
| GET /v1/ai/routines | List routines for the calling user, newest first. | v1 (latest) |
| GET /v1/ai/routines/:routineId | Retrieve details for a specific routine by ID, including the status of its most recent completed run. | v1 (latest) |
| POST /v1/ai/routines/:routineId/trigger | Run an existing routine immediately, in addition to its schedule. | v1 (latest) |
| DELETE /v1/ai/routines/:routineId | Delete a routine. | v1 (latest) |
API tokens
| Endpoint | Description | Version + Status |
|---|---|---|
| PUT /v1/api-keys/:id | Disable or re-enable an API token. | v1 (latest) |
| GET /v1/api-keys | List API token in the organization - including Organization API keys, Personal Access Tokens, and MCP OAuth grants - with optional filtering by type. | v1 (latest) |
| GET /v1/api-keys/:id | Retrieve a single API token by ID. | v1 (latest) |
| DELETE /v1/api-keys/:id | Permanently delete an API token. | v1 (latest) |
Connections
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/connections | Create a new database connection. | v1 (latest) |
| PATCH /v1/connections/:connectionId | Update connection properties including credentials. | v1 (latest) |
| GET /v1/connections | Retrieve a list of database connections with optional filtering and sorting. | v1 (latest) |
| GET /v1/connections/:connectionId | Fetch a single connection by ID. | v1 (latest) |
| DELETE /v1/connections/:connectionId | Archive a connection (moves it to trash). | v1 (latest) |
Connection environments
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/connection-environments | Create a connection environment and associate it with a base connection. | v1 (latest) |
| PUT /v1/connection-environments/:connectionEnvironmentId | Associate user attribute values with a specific connection environment to determine when the environment is used. | v1 (latest) |
| DELETE /v1/connection-environments/:connectionEnvironmentId | Delete a connection environment by ID. | v1 (latest) |
dbt configuration
| Endpoint | Description | Version + Status |
|---|---|---|
| PUT /v1/connections/:connectionId/dbt | Update the dbt configuration for the specified connection. | v1 (latest) |
| GET /v1/connections/:connectionId/dbt | Retrieve the dbt configuration for the specified connection. | v1 (latest) |
| DELETE /v1/connections/:connectionId/dbt | Remove the dbt configuration for the specified connection. | v1 (latest) |
dbt environments
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/connections/:connectionId/dbt/environments | Create a new dbt environment on the specified connection, enabling programmatic environment management. | v1 (latest) |
| PUT /v1/connections/:connectionId/dbt/environments/:environmentId | Update an existing dbt environment on the specified connection. | v1 (latest) |
| GET /v1/connections/:connectionId/dbt/environments | Retrieve a list of all dbt environments configured for the specified connection. | v1 (latest) |
| DELETE /v1/connections/:connectionId/dbt/environments/:environmentId | Delete an existing dbt environment from the specified connection. | v1 (latest) |
Schema refreshes
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/connections/:connectionId/schedules | Create a new schema refresh schedule for the specified connection. | v1 (latest) |
| PUT /v1/connections/:connectionId/schedules/:scheduleId | Update the schedule and/or timezone for an existing schema refresh schedule. | v1 (latest) |
| GET /v1/jobs/:jobId/status | Retrieve the current status of an asynchronous job. | v1 (latest) |
| GET /v1/connections/:connectionId/schedules | Retrieve all schema refresh schedules configured for the specified connection. | v1 (latest) |
| GET /v1/connections/:connectionId/schedules/:scheduleId | Retrieve the details of a connection’s specific schema refresh schedule. | v1 (latest) |
| DELETE /v1/connections/:connectionId/schedules/:scheduleId | Delete a schema refresh schedule. | v1 (latest) |
Content
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/content | Retrieve a paginated list of documents and folders. | v1 (latest) |
| GET /unstable/documents/:dashboardId/export | Export a dashboard for migration between Omni instances. | unstable (beta) |
| POST /unstable/documents/import | Import a dashboard to an Omni instance. | unstable (beta) |
Dashboards
Downloads
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/dashboards/:dashboardId/download | Start an asynchronous download job for a dashboard or single tile with support for multiple output formats. | v1 (latest) |
| GET /v1/dashboards/:dashboardId/download/:jobId/status | Retrieve the current status of a dashboard or tile download job. Poll this endpoint to determine when the file is ready. | v1 (latest) |
| GET /v1/dashboards/:dashboardId/download/:jobId | Retrieve the completed dashboard or tile download file. | v1 (latest) |
Filters
| Endpoint | Description | Version + Status |
|---|---|---|
| PATCH /v1/dashboards/:dashboardId/filters | Set or reset values for filters and/or controls on a dashboard. | v1 (latest) |
| GET /v1/dashboards/:dashboardId/filters | Retrieve the filter and control configuration for a dashboard. | v1 (latest) |
Documents
Draft and publish
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v2/documents | Create a brand-new document and publish it. | v2 (latest) |
| PATCH /v2/documents/:documentId/draft | Create a new draft on the published document and apply the patch. | v2 (latest) |
| PATCH /v2/documents/:documentId/draft/:draftId | Apply a patch to an existing draft addressed by draftId. | v2 (latest) |
| POST /v2/documents/:documentId/draft/publish | Publish the document’s current main (non-branch) draft, promoting it to the published version. | v2 (latest) |
| POST /v1/documents/:documentId/upgrade | Upgrade a classic document to the new dashboard editor. | v1 (latest) |
| GET /v2/documents/:documentId | Read the document’s published state. | v2 (latest) |
| GET /v1/documents/:documentId/drafts | List all drafts attached to a published document. | v1 (latest) |
| GET /v2/documents/:documentId/draft/:draftId | Read the named draft’s state. | v2 (latest) |
| DELETE /v1/documents/:documentId/draft | Archive the current draft of the specified document. | v1 (latest) |
| DELETE /v2/documents/:documentId/draft/:draftId/dashboard | Remove the dashboard from an existing draft, leaving a workbook-only document. | v2 (latest) |
| DELETE /v1/documents/:documentId | Delete document (moves to Trash). | v1 (latest) |
Favorites
| Endpoint | Description | Version + Status |
|---|---|---|
| PUT /v1/documents/:documentId/favorite | Add a document to a user’s favorites. | v1 (latest) |
| GET /v1/documents/:documentId/favorites | List users who have favorited a published document, paginated and sorted by favoritedAt. | v1 (latest) |
| DELETE /v1/documents/:documentId/favorite | Remove a document from a user’s favorites. | v1 (latest) |
Labels
| Endpoint | Description | Version + Status |
|---|---|---|
| PATCH /v1/documents/:documentId/labels | Add and/or remove multiple labels from a document in a single atomic operation. | v1 (latest) |
| PUT /v1/documents/:documentId/labels/:labelName | Apply an existing label to a document. | v1 (latest) |
| DELETE /v1/documents/:documentId/labels/:labelName | Remove an existing label from a document. | v1 (latest) |
Management
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/documents | List documents with pagination and filtering. | v1 (latest) |
| PUT /v2/documents/:documentId/identifier | Rename a published document’s identifier. | v2 (latest) |
| PUT /v1/documents/:documentId/move | Move document to new folder or change scope. | v1 (latest) |
| POST /v1/documents/:documentId/duplicate | Duplicate a published document. | v1 (latest) |
| PUT /v1/documents/:documentId/transfer-ownership | Transfer ownership of a document to another user in the organization. | v1 (latest) |
Permissions
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/documents/:documentId/permissions | Grant document permissions to users or groups. | v1 (latest) |
| PUT /v1/documents/:documentId/permissions | Update the permission and interactivity settings for a document. | v1 (latest) |
| PATCH /v1/documents/:documentId/permissions | Update existing document permissions for users or groups. | v1 (latest) |
| GET /v1/documents/:documentId/access-list | List all users and groups with access to a document. | v1 (latest) |
| GET /v1/documents/:documentId/permissions | Retrieve the document-level ability values, plus the resolved permits for a specific user when userId is provided. | v1 (latest) |
| DELETE /v1/documents/:documentId/permissions | Revoke document permissions for users or user groups. | v1 (latest) |
Deprecated (v1)
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/documents | Create a new document. | v1 (deprecated) |
| POST /v1/documents/:documentId/draft | Create a draft of the specified document. | v1 (deprecated) |
| PUT /v1/documents/:documentId | Update a document with the specified identifier. | v1 (deprecated) |
| PATCH /v1/documents/:documentId | Update the name, description, and/or identifier of a document. | v1 (deprecated) |
| GET /v1/documents/:documentId/queries | Retrieve queries associated with a document by its identifier. | v1 (deprecated) |
| GET /v1/documents/:documentId | Retrieve dashboard document configuration in a format compatible with PUT for round-trip editing. | v1 (deprecated) |
Folders
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/folders | Retrieve a paginated list of folders within an organization. | v1 (latest) |
| POST /v1/folders | Create a new folder. | v1 (latest) |
| PATCH /v1/folders/:folderId | Update a folder’s name and/or path segment. | v1 (latest) |
| DELETE /v1/folders/:folderId | Delete a folder. | v1 (latest) |
Permissions
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/folders/:folderId/permissions | Grant folder permissions to users or groups. | v1 (latest) |
| PATCH /v1/folders/:folderId/permissions | Update existing folder permissions for users or groups. | v1 (latest) |
| GET /v1/folders/:folderId/permissions | Retrieve folder permissions for a user. | v1 (latest) |
| DELETE /v1/folders/:folderId/permissions | Revoke folder permissions from users or groups. | v1 (latest) |
Labels
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/labels | Create a new label in the organization. | v1 (latest) |
| PUT /v1/labels/:labelName | Update an existing label. | v1 (latest) |
| GET /v1/labels | Retrieve all labels in the organization. | v1 (latest) |
| GET /v1/labels/:labelName | Retrieve a single label by name. | v1 (latest) |
| DELETE /v1/labels/:labelName | Delete a label from the organization. | v1 (latest) |
Models
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/models | Create a new model. | v1 (latest) |
| PATCH /v1/models/:modelId | Rename a model. | v1 (latest) |
| POST /v1/models/:modelId/refresh | Refresh the schema of the specified model. | v1 (latest) |
| GET /v1/models | Retrieve a paginated list of models with their metadata. | v1 (latest) |
| GET /v1/models/:modelId/validate | Retrieve validation issues for a model and its branches. | v1 (latest) |
Branches
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/models/:modelId/branch/:branchName/merge | Merge a model branch into the shared model. | v1 (latest) |
| POST /v1/models/:modelId/branch/:branchName/dbt | Set the active dbt environment on a model branch. | v1 (latest) |
| DELETE /v1/models/:modelId/branch/:branchName | Delete a branch associated with the specified shared model. | v1 (latest) |
Content validator
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/models/:modelId/content-validator | Validate all content against the model and return documents with queries and any validation issues. | v1 (latest) |
| POST /v1/models/:modelId/content-validator | Perform find/replace operations on content using the specified model. | v1 (latest) |
Management
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/models/:modelId/ai-agent-actions | Return AI agent actions configured for a model. | v1 (latest) |
| POST /v1/models/:modelId/cache_reset/:cachePolicyName | Reset the cache for the specified cache policy. | v1 (latest) |
| GET /v1/models/:modelId/schemas | Retrieve a sorted list of all available schema names for the specified model, including physical, virtual, and dynamic schemas. | v1 (latest) |
| GET /v1/models/:modelId/dbt-exposures | Retrieve dbt exposures for the specified model. | v1 (latest) |
Git
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/models/:modelId/git | Retrieve the Git configuration for a shared model. | v1 (latest) |
| POST /v1/models/:modelId/git | Create a new Git configuration for a shared model. | v1 (latest) |
| PATCH /v1/models/:modelId/git | Update the Git configuration for a shared model. | v1 (latest) |
| DELETE /v1/models/:modelId/git | Remove the Git configuration from a shared model. | v1 (latest) |
| POST /v1/models/:modelId/git/sync | Trigger a sync operation between the model and its configured Git repository. | v1 (latest) |
| POST /v1/models/:modelId/git/commit | Push a branch’s model contents to Git and create or update a pull request. | v1 (latest) |
| POST /v1/models/:modelId/migrate | 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. | v1 (latest) |
Topics
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/models/:modelId/topic/:topicName | Retrieve a topic in a model by name. | v1 (latest) |
Views
| Endpoint | Description | Version + Status |
|---|---|---|
| DELETE /v1/models/:modelId/view/:viewName | Delete or ignore a view in a model. | v1 (latest) |
YAML files
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/models/:modelId/yaml | Create or overwrite a YAML file for a model. | v1 (latest) |
| GET /v1/models/:modelId/yaml | Retrieve the YAML representation of a model with optional filtering and mode selection. | v1 (latest) |
| DELETE /v1/models/:modelId/yaml | Delete a topic or view YAML file from a model. | v1 (latest) |
Queries
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/query/run | Run the query specified in the request body. | v1 (latest) |
| GET /v1/query/wait | Poll for the results of one or more query jobs. | v1 (latest) |
Schedules
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/schedules | Create a scheduled task for the specified dashboard. | v1 (latest) |
| PUT /v1/schedules/:scheduleId | Update the specified task. Changes are applied to future runs; in-progress jobs are unaffected. | v1 (latest) |
| PUT /v1/schedules/:scheduleId/transfer-ownership | Immediately transfer ownership of a schedule from one user to another user in the same organization. | v1 (latest) |
| GET /v1/schedules | Retrieve a list of scheduled tasks. | v1 (latest) |
| GET /v1/schedules/:scheduleId | Return the details of a single schedule, including its delivery destinations, recurrence configuration, and current status. | v1 (latest) |
| DELETE /v1/schedules/:scheduleId | Delete a schedule. | v1 (latest) |
Runs
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/schedules/:scheduleId/trigger | Trigger the execution of a schedule on demand. | v1 (latest) |
| PUT /v1/schedules/:scheduleId/pause | Pause a schedule. | v1 (latest) |
| PUT /v1/schedules/:scheduleId/resume | Resume a schedule. | v1 (latest) |
Recipients
| Endpoint | Description | Version + Status |
|---|---|---|
| PUT /v1/schedules/:scheduleId/add-recipients | Add one or more recipients to an existing scheduled email task. | v1 (latest) |
| PUT /v1/schedules/:scheduleId/remove-recipients | Remove one or more recipients from an existing scheduled email task. | v1 (latest) |
| POST /v1/users/email-only | Create or update an email-only user. | v1 (latest) |
| POST /v1/users/email-only/bulk | Create or update up to 20 email-only users. | v1 (latest) |
| GET /v1/schedules/:scheduleId/recipients | Retrieve the list of recipients for the specified schedule. | v1 (latest) |
Uploads
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/uploads | Upload a CSV file to create a new data input table. | v1 (latest) |
| GET /v1/uploads | List all uploads (CSV files and spreadsheets) in the organization. | v1 (latest) |
| DELETE /v1/uploads/:uploadId | Delete a CSV upload by its ID. | v1 (latest) |
Users
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /scim/v2/users | Create a user. | v2 (latest) |
| PUT /scim/v2/users/:userId | Replace the specified user. | v2 (latest) |
| PATCH /scim/v2/users/:userId | Update the specified user by applying a list of SCIM 2.0 patch operations. | v2 (latest) |
| GET /scim/v2/users/:userId | Retrieve a user using their unique ID. | v2 (latest) |
| GET /scim/v2/users | Return a list of users, sorted by creation time. | v2 (latest) |
| DELETE /scim/v2/users/:userId | Delete the specified user. | v2 (latest) |
Email-only users
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/users/email-only | Retrieve email-only users with their user attributes, with support for cursor-based pagination and filtering. | v1 (latest) |
Embed users
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /scim/v2/embed/users | Retrieve a list of embed users, sorted by creation time. | v2 (latest) |
| GET /scim/v2/embed/users/:userId | Retrieve an embed user using their unique ID. | v2 (latest) |
| DELETE /scim/v2/embed/users/:userId | Delete the specified embed user. | v2 (latest) |
Model roles
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/users/:userId/model-roles | Assign or update a model role for a user. | v1 (latest) |
| GET /v1/users/:userId/model-roles | Retrieve the model role assignments for a user. | v1 (latest) |
User attributes
| Endpoint | Description | Version + Status |
|---|---|---|
| GET /v1/user-attributes | Retrieve all user attribute definitions in the organization, including custom-defined and system-defined attributes. | v1 (latest) |
User groups
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /scim/v2/groups | Create a user group. | v2 (latest) |
| PUT /scim/v2/groups/:userGroupId | Replace the specified user group. | v2 (latest) |
| PATCH /scim/v2/groups/:userGroupId | Update the specified user group by applying a list of v2 patch operations. | v2 (latest) |
| GET /scim/v2/groups | Return a list of user groups, sorted by creation time. | v2 (latest) |
| GET /scim/v2/groups/:userGroupId | Retrieve a user group using its unique ID. | v2 (latest) |
| DELETE /scim/v2/groups/:userGroupId | Delete the specified user group. | v2 (latest) |
Model roles
| Endpoint | Description | Version + Status |
|---|---|---|
| POST /v1/user-groups/:userGroupId/model-roles | Assign or update a model role for a user group. | v1 (latest) |
| GET /v1/user-groups/:userGroupId/model-roles | Retrieve the model role assignments for a user group. | v1 (latest) |