> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
# List document drafts
>
This endpoint requires **Viewer** permissions or higher on the specified document.
List all drafts attached to a published document. A document in Omni can have up to one draft per branch plus one draft not attached to a branch.
By default, returns active drafts only. Pass `?include=archived` to include soft-deleted drafts retained for approximately 7 days.
## OpenAPI
````yaml /api/openapi.yaml get /v1/documents/{identifier}/drafts
openapi: 3.1.0
info:
title: Omni API
description: >
The Omni REST API provides programmatic access to your Omni instance for
managing users, documents, queries, schedules, and more.
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: AI
description: AI-powered query generation
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Content
description: Unified content retrieval (documents and folders)
- name: Content migration
description: Export and import dashboards
- name: Content validator
description: Validate content against models and perform find/replace operations
- name: Dashboard downloads
description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
- name: Dashboard filters and controls
description: Read and update dashboard filter and control default values
- name: dbt
description: Manage dbt configuration for connections
- name: Documents
description: Create, retrieve, and manage documents
- name: Document favorites
description: Favorite and unfavorite documents
- name: Document labels
description: Apply and manage labels on documents
- name: Document permissions
description: Manage document-level access
- name: Labels
description: >
Manage labels in an organization. Labels can be applied to documents and
folders to help organize and categorize content.
**Label types:**
- **Basic labels**: Can be created and managed by any user
- **Verified labels**: Indicate curated or officially sanctioned content.
Admin-only.
- **Homepage labels**: Appear on the organization homepage. Admin-only.
- name: Folders
description: Create and organize content folders
- name: Folder permissions
description: Manage folder-level access
- name: Jobs
description: Check status of asynchronous jobs
- name: Models
description: Create and manage data models
- name: Model branches
description: Manage model branches and merge changes
- name: Model git configuration
description: Manage git configuration for shared models
- name: Queries
description: Execute workbook queries
- name: Schedules
description: Create and manage scheduled tasks
- name: Schedule recipients
description: Manage schedule recipients
- name: Schema refresh schedules
description: Manage automated schema refresh schedules for connections
- name: Topics
description: Retrieve topic information from models
- name: Uploads
description: Manage file uploads
- name: Users
description: Manage users
- name: User attributes
description: Manage user attribute definitions
- name: User groups
description: Manage user groups
- name: User model roles
description: Manage model and connection role assignments for users
- name: User group model roles
description: Manage model and connection role assignments for user groups
- name: Uploads
description: Manage CSV and spreadsheet uploads
paths:
/v1/documents/{identifier}/drafts:
get:
tags:
- Documents
summary: List document drafts
description: >
This endpoint requires **Viewer** permissions or higher on the specified document.
List all drafts attached to a published document. A document in Omni can
have up to one draft per branch plus one draft not attached to a branch.
By default, returns active drafts only. Pass `?include=archived` to
include soft-deleted drafts retained for approximately 7 days.
operationId: listDocumentDrafts
parameters:
- name: identifier
in: path
required: true
schema:
type: string
description: >
The identifier of the published document. To retrieve the ID,
navigate to **File > Document settings** in the document and then
click **Settings**. The **Identifier** field contains the document
ID.
- name: include
in: query
required: false
schema:
type: string
enum:
- archived
description: >
Pass `archived` to include soft-deleted drafts in the response. By
default, only active drafts are returned.
example: archived
responses:
'200':
description: >
List of drafts retrieved successfully. Results are sorted in
descending order using the draft's `updatedAt`.
content:
application/json:
schema:
type: array
items:
type: object
properties:
identifier:
type: string
description: The identifier of the draft.
example: d56b7f56
publishedIdentifier:
type: string
description: >-
The identifier of the published document this draft is
attached to.
example: ecd01fe5
workbookModelId:
type: string
format: uuid
description: The UUID of the workbook model.
example: d61034e2-05fe-4268-a3a7-d4cdb8d650e9
branch:
type: object
nullable: true
description: >-
The branch this draft is attached to, or `null` for
draft not attached to a branch. A document can only have
one draft not attached to a branch.
properties:
id:
type: string
format: uuid
description: The UUID of the branch.
name:
type: string
nullable: true
description: >-
The name of the branch. Can be `null` if the branch
is unnamed.
example:
id: a9bc51d2-1234-5678-9abc-def012345678
name: governance/relabel-age-average
status:
type: string
enum:
- active
- archived
description: The status of the draft.
example: active
draftOutOfDate:
type: boolean
description: >-
Indicates whether the draft is [out of
date](/content/develop/branch-mode#working-with-out-of-date-drafts)
compared to the published document.
example: false
createdAt:
type: string
format: date-time
description: Timestamp when the draft was created.
example: '2026-05-06T13:44:00.000Z'
updatedAt:
type: string
format: date-time
description: Timestamp when the draft was last updated.
example: '2026-05-06T13:44:26.000Z'
createdBy:
type: object
description: User who created the draft.
properties:
name:
type: string
description: Display name of the user who created the draft.
example:
name: Blob Ross
lastEditedBy:
type: object
description: User who last edited the draft.
properties:
name:
type: string
description: Display name of the user who last edited the draft.
example:
name: Blob Ross
example:
- identifier: d56b7f56
publishedIdentifier: ecd01fe5
workbookModelId: d61034e2-05fe-4268-a3a7-d4cdb8d650e9
branch:
id: a9bc51d2-1234-5678-9abc-def012345678
name: governance/relabel-age-average
status: active
draftOutOfDate: false
createdAt: '2026-05-06T13:44:00.000Z'
updatedAt: '2026-05-06T13:44:26.000Z'
createdBy:
name: Blob Ross
lastEditedBy:
name: Blob Ross
'400':
description: |
Bad Request
Possible error messages:
- `Invalid include parameter value`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: >
Forbidden
Possible error messages:
- `You do not have permission to view this document.` -
Authenticating user must have **Viewer** permissions or higher on
the document
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: >
Not Found
Possible error messages:
- `Document with identifier not found`
- `Published document with id does not exist` -
Document exists but has not been published
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
components:
schemas:
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
TooManyRequests:
description: Too Many Requests - Rate limit exceeded (60 requests/minute)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Can be either an [Organization API
Key](/api/authentication#organization-api-keys) or [Personal Access
Token (PAT)](/api/authentication#personal-access-tokens-pat).
Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
orgApiKey:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Requires an [Organization API
Key](/api/authentication#organization-api-keys). Personal Access Tokens
(PATs) are not supported for this endpoint.
Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`
````