OpenAPI Specification
openapi: 3.1.0
info:
title: Omni AI Documents API
description: "The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. \n"
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: Documents
description: Create, retrieve, and manage documents
paths:
/v1/documents:
post:
tags:
- Documents
summary: Create document
deprecated: true
description: "<Warning>\n **Deprecated** — Removal scheduled for **July 31, 2026**. Use the [Documents v2 API](/api/documents-v2/create-document) instead.\n</Warning>\n\nCreate a new document\n"
security:
- bearerAuth: []
operationId: createDocument
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- modelId
- name
properties:
modelId:
type: string
format: uuid
description: The ID of the model to build the document on
name:
type: string
description: The name of the document
description:
type: string
minLength: 1
maxLength: 1024
description: Description of the document
identifier:
type: string
description: 'Custom identifier for the document. If not provided, an identifier will be auto-generated.
The identifier is used in the document''s URL and must be unique across all documents in your organization.
**Format requirements:**
- Must match the pattern: lowercase letters, numbers, hyphens, and underscores only
- Cannot start or end with a hyphen or underscore
**Note:** Once created, the identifier can be changed using the [Update document endpoint](/api/documents/update-document).
'
example: sales-dashboard-2026
queryPresentations:
type: array
description: An array of query presentation objects, each representing a query in the document's workbook
items:
type: object
properties:
name:
type: string
description: The name of the query
description:
type: string
description: A description of the query
query:
type: object
description: The query definition object
visConfig:
type: object
description: Visualization configuration for the query
examples:
basicDocument:
summary: Create document with auto-generated identifier
value:
modelId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: Sales Dashboard
description: Q1 2026 sales performance metrics
customIdentifier:
summary: Create document with custom identifier
value:
modelId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: Sales Dashboard
identifier: sales-dashboard-2026
description: Q1 2026 sales performance metrics
responses:
'200':
description: Document created successfully
headers:
Deprecation:
description: Indicates that this endpoint is deprecated
schema:
type: string
example: 'true'
Sunset:
description: The date this endpoint will be removed (RFC 9110)
schema:
type: string
format: date
example: '2026-07-31'
Link:
description: Link to the replacement API (RFC 8288)
schema:
type: string
example: </api/documents-v2/create-document>; rel="successor-version"
content:
application/json:
schema:
type: object
properties:
dashboard:
type: object
properties:
id:
type: string
format: uuid
description: The dashboard ID
createdAt:
type: string
format: date-time
description: Timestamp when the dashboard was created
updatedAt:
type: string
format: date-time
description: Timestamp when the dashboard was last updated
metadata:
type: object
description: Dashboard metadata including layouts and tile settings
properties:
layouts:
type: object
description: Layout configurations for different screen sizes
textTiles:
type: array
items:
type: object
hiddenTiles:
type: array
items:
type: string
tileSettings:
type: object
tileFilterMap:
type: object
tileControlMap:
type: object
metadataVersion:
type: integer
description: Version of the metadata schema
refreshInterval:
type: integer
description: Auto-refresh interval in seconds
facetFilters:
type: boolean
description: Whether facet filters are enabled
organizationId:
type: string
format: uuid
description: The organization ID
workbookId:
type: string
format: uuid
description: The associated workbook ID
creatorId:
type: string
format: uuid
description: The ID of the user who created the dashboard
updaterId:
type: string
format: uuid
description: The ID of the user who last updated the dashboard
queryPresentationCollectionId:
type: string
format: uuid
description: The query presentation collection ID
dashboardId:
type: string
format: uuid
description: The dashboard ID (same as id)
workbook:
type: object
properties:
id:
type: string
format: uuid
description: The workbook ID
createdAt:
type: string
format: date-time
description: Timestamp when the workbook was created
updatedAt:
type: string
format: date-time
description: Timestamp when the workbook was last updated
deletedAt:
type: string
format: date-time
description: Timestamp when the workbook was deleted, if applicable
publishedAt:
type: string
format: date-time
description: Timestamp when the workbook was published
isDraft:
type: boolean
description: Whether the workbook is a draft
identifier:
type: string
description: The unique identifier for the document
name:
type: string
description: The name of the document
lastItemIndex:
type: integer
description: Index of the last item in the workbook
ephemeral:
type: string
description: Ephemeral state identifier
organizationRole:
type: string
description: Organization-level role for the document
organizationAccessBoost:
type: boolean
publicRole:
type: string
publicAccessBoost:
type: boolean
canAnalyze:
type: boolean
description: Whether users can analyze data in the document
canDownload:
type: boolean
description: Whether users can download data from the document
canDrill:
type: boolean
description: Whether users can drill into data in the document
canSchedule:
type: boolean
description: Whether users can create schedules in the document
canUpload:
type: boolean
description: Whether users can upload data in the document's workbook
canViewWorkbook:
type: boolean
description: Whether users can view the workbook in the document
canUseTimezoneOverride:
type: boolean
description: Whether users can use the [timezone picker](/visualize-present/dashboards/timezone-override) to change the query timezone for this document
organizationId:
type: string
format: uuid
description: The organization ID
ownerId:
type: string
format: uuid
description: The ID of the document owner
updaterId:
type: string
format: uuid
description: The ID of the user who last updated the document
folderId:
type: string
format: uuid
description: The folder ID, if the document is in a folder
originDocumentId:
type: string
format: uuid
description: The origin document ID, if duplicated
documentId:
type: string
format: uuid
description: The document ID
'400':
description: 'Bad Request
Possible error messages:
- `modelId: Required`
- `name: Required`
- Identifier format is invalid (must be lowercase letters, numbers, hyphens, and underscores; cannot start/end with hyphen or underscore)
- Identifier is already in use by another document
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
get:
tags:
- Documents
summary: List documents
description: List documents with pagination and filtering
security:
- bearerAuth: []
operationId: listDocuments
parameters:
- name: include
in: query
schema:
type: string
description: "Comma-separated list of additional fields to include in the response:\n- `_count` - Adds favorite and view count metrics\n- `labels` - Includes associated document labels\n- `includeDeleted` - Include deleted documents\n- `onlyFavorites` - **Must be used with `userId`.** Include only documents that the specified user has favorited.\n- `onlySharedWithMe` - Returns only documents explicitly shared with the specified user via documents permissions. Excludes documents owned by the user. Cannot be combined with `ownerId` or `path`.\n\n Additionally, depending on the type of API key being used:\n\n - **Organization API keys** require the `userId` parameter\n - **Personal Access Tokens** automatically infer the `userId` from the token\n"
- name: labels
in: query
schema:
type: string
description: 'Comma-separated list of labels to filter results. For example: `finance,marketing`
'
- name: folderId
in: query
schema:
type: string
format: uuid
description: ID of the folder to filter results. Returns only documents within the specified folder.
- name: pageSize
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Number of records per page
- name: sortField
in: query
schema:
type: string
enum:
- favorites
- name
- updatedAt
- visits
default: name
description: 'Field to sort by:
- `favorites` - Sort by the number of favorites
- `name` - Sort by document name
- `updatedAt` - Sort by last update time
- `visits` - Sort by view count
'
- name: sortDirection
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
description: Sort direction (`asc` for ascending, `desc` for descending)
- name: cursor
in: query
schema:
type: string
description: Cursor for pagination. Used with `sortField`/`sortDirection` for relative positioning.
- name: userId
in: query
schema:
type: string
format: uuid
description: 'The ID of a standard or embed user to filter results, returning only documents the specified user can view based on their permissions.
If `include=onlyFavorites` is specified:
- **And using an Organization API key**, this parameter is **required**
- **And using a Personal Access Token**, the `userId` will be automatically inferred from the token
'
- name: creatorId
in: query
schema:
type: string
format: uuid
description: ID of the user who created the document(s), returning only documents that the specified user created.
responses:
'200':
description: Paginated document list
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentsListResponse'
'400':
description: 'Bad Request
Possible error messages:
- `pageSize: Page size must be at least 1`
- `pageSize: Page size cannot exceed 100`
- `sortField: Invalid enum value. Expected ''favorites'' | ''name'' | ''updatedAt'' | ''visits'', received ''<invalidField>''`
- `creatorId: Invalid uuid`
- `userId: Invalid uuid`
- `formErrors: Unrecognized key(s) in object: ''<unknownParameter>''`
- `onlySharedWithMe requires userId` - When using `include=onlySharedWithMe` without providing a `userId` parameter
- `onlySharedWithMe cannot be combined with onlyFavorites` - When using both `include=onlySharedWithMe` and `include=onlyFavorites` together
- `onlySharedWithMe cannot be combined with folderId` - When using `include=onlySharedWithMe` with a `folderId` parameter
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: 'Not Found
Possible error messages:
- `User with id <uuid> does not exist`
**Note**: An invalid UUID format will result in a 400 error. This 404 error occurs when the provided ID is a valid UUID format but the user cannot be found.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/documents/{documentId}/move:
put:
tags:
- Documents
summary: Move document
description: 'Move document to new folder or change scope.
'
security:
- bearerAuth: []
operationId: moveDocument
parameters:
- name: documentId
in: path
required: true
schema:
type: string
description: 'The ID of the document to move. To retrieve the ID, navigate to **File > Document settings** in the document and then click **Settings**. The **Identifier** field contains the document ID.
'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- folderPath
properties:
folderPath:
oneOf:
- type: string
- type: 'null'
description: The path of the destination folder. Use `null` to move the document to the root level (no folder).
scope:
type: string
enum:
- organization
- restricted
description: 'Optional sharing scope for the document:
- `organization` - Organization-wide access
- `restricted` - Limited access
If not provided, the scope will be computed based on the document or the destination folder.
**Note**: When providing a scope, it must match the destination folder''s scope.
'
responses:
'200':
description: Document moved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: 'Bad Request
Possible error messages:
- `Scope "<scope>" and folder scope "<folderScope>" do not match`
- `Invalid method`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Forbidden
Possible error messages/causes:
- `User-scoped API keys cannot act on behalf of other users`
- Operations targeting personal/restricted scope require the user''s **Personal content access** setting (`omni_allows_personal_content` system attribute) to be enabled for the user. If not enabled, the API will respond with `403 Forbidden`.
'
'404':
description: 'Not Found
Possible error messages:
- `Document with identifier "<documentId>" not found`
- `Folder with path <path> does not exist`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/documents/{documentId}/duplicate:
post:
tags:
- Documents
summary: Duplicate published document
x-mint:
content: "<Warning>\n Only published documents can be duplicated. Attempting to duplicate a draft document will return a 404 error.\n</Warning>\n\nDuplicate a published document.\n"
security:
- bearerAuth: []
operationId: duplicateDocument
parameters:
- name: documentId
in: path
required: true
schema:
type: string
description: Document identifier
- name: userId
in: query
schema:
type: string
description: '**Requires an Organization API key**. Optional user ID that attributes the action to the specified user.
'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 255
description: The name for the duplicated document
folderPath:
oneOf:
- type: string
- type: 'null'
description: Path to the destination folder. If not provided, the document will be duplicated to the root.
scope:
type: string
enum:
- organization
- restricted
description: 'The visibility scope for the duplicated document.
If not provided, inherits from the destination folder or defaults to `restricted`.
'
example:
name: My Dashboard Copy
folderPath: /reports/2024/q4
scope: organization
responses:
'201':
description: Document duplicated successfully
content:
application/json:
schema:
type: object
properties:
dashboardId:
type: string
description: The dashboard ID, if the duplicated document has a dashboard
identifier:
type: string
description: Unique identifier for the newly created document
name:
type: string
description: The name of the duplicated document
workbookId:
type: string
description: The workbook ID of the duplicated document
example:
dashboardId: abc123-dash-id
identifier: xyz789-new-identifier
name: My Dashboard Copy
workbookId: def456-workbook-id
'400':
description: 'Bad Request. Possible error messages:
- `name: Name cannot be empty`
- `name: Name must be 255 characters or less`
- `Scope "organization" and folder scope "restricted" do not match`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Insufficient permissions. Possible error messages/causes:
- `User does not have access to create content on the specified connection`
- `User-scoped API keys can only be used to act on behalf of the authenticated user.`
- `Document duplication is disabled`. The document''s duplication permission is disabled.
- Operations targeting personal/restricted scope require the user''s **Personal content access** setting (`omni_allows_personal_content` system attribute) to be enabled for the user. If not enabled, the API will respond with `403 Forbidden`.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: 'Not Found. Possible error messages:
- `Document with identifier "<documentId>" not found`
- `Published document with id "<documentId>" does not exist`. This will surface when attempting to duplicate a draft.
- `Folder with path "<folderPath>" does not exist`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/documents/{identifier}/upgrade:
post:
tags:
- Documents
summary: Upgrade dashboard layout
description: "Upgrade a document to the advanced dashboard layout — the same action available in the UI under **File > Upgrade layout**.\n\n<Note>\n This operation is idempotent. If the document already uses the advanced layout, the request is a no-op and returns `upgraded: false`.\n</Note>\n\nFor published documents the upgrade runs through a draft-and-publish workflow automatically. If a draft already exists, the request returns `409` unless `clearExistingDraft` is set to `true`, which discards the existing draft before upgrading.\n"
operationId: documentsUpgradeLayout
parameters:
- name: identifier
in: path
required: true
schema:
type: string
description: Document identifier (either document ID or identifier slug)
example: abc123
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentsUpgradeLayoutBody'
example:
clearExistingDraft: true
responses:
'200':
description: Layout upgraded, or no-op if the document already had advanced layout.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentsUpgradeLayoutResponse'
example:
identifier: abc123
upgraded: true
'400':
description: 'Bad Request
- The document does not have a dashboard to upgrade.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError401'
'403':
description: Permission denied
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: Document not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'409':
description: A draft already exists for the published document; set `clearExistingDraft` to `true` to override.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError409'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/documents/{documentId}/transfer-ownership:
put:
tags:
- Documents
summary: Transfer document ownership
description: "Transfer ownership of a document to another user in the organization.\n\nTo successfully transfer a document: \n\n- The user performing the transfer must have `MANAGER` permissions or higher on the document\n- The new owner must be a member of the organization AND have explicit access to the document\n\nUpon success, the following occurs: \n\n- Ownership of the document is updated to the new owner\n- The previous owner is granted `MANAGER` permissions on the document\n- Explicit permits for the new owner are revoked, as they now have owner access\n- Content search index is updated\n\n**Note:** Transferring to the current owner is a no-op and returns success.\n"
security:
- bearerAuth: []
operationId: transferDocumentOwnership
parameters:
- name: documentId
in: path
required: true
schema:
type: string
description: 'The ID of the document to transfer. To retrieve the ID, navigate to **File > Document settings** in the document and then click **Settings**. The **Identifier** field contains the document ID.
'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- userId
properties:
userId:
type: string
description: The membership ID of the user to transfer ownership to. This must be a valid organization member who has explicit permission on the document.
example:
userId: 9e8719d9-276a-4964-9395-a493189a247c
responses:
'200':
description: 'Document ownership transferred successfully.
**Note:** This response is also returned when transferring to the current owner.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
success: true
'400':
description: 'Bad Request
Possible error messages:
- `Invalid JSON`
- `userId is required`
- `New owner must have explicit document permission`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidJson:
summary: Invalid JSON body
value:
error: Invalid JSON
missingUserId:
summary: Missing userId field
value:
error: userId is required
noPermission:
summary: New owner lacks document permission
value:
error: New owner must have explicit document permission
'403':
description: 'Forbidden
Possible error messages:
- `Insufficient permissions` - Acting user does not have `MANAGER` or higher permissions on the document
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Insufficient permissions
'404':
description: 'Not Found
Possible error messages:
- `Document with identifier "<documentId>" not found`
- `User not found`
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
documentNotFound:
summary: Document not found
value:
error: Document with identifier "doc-123" not found
userNotFound:
summary: User not found
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/omni/refs/heads/main/openapi/omni-documents-api-openapi.yml