> ## 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.

# Get draft state

> Read the named draft's state. Returns the same `DocumentsV2ReadResponse` shape as [Get document state](/api/documents-v2/get-document-state), and is round-trippable as a `PATCH` body.




## OpenAPI

````yaml /api/openapi.yaml get /v2/documents/{documentId}/draft/{draftId}
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: Who Am I
    description: Inspect your own user permissions
  - name: AI
    description: AI-powered query generation
  - name: AI Credit Controls
    description: Manage organization-level AI credit usage
  - name: AI Eval
    description: >-
      AI evaluation: manage prompt sets and runs used to score AI quality
      against curated prompt suites.
  - name: AI Model Suggestions
    description: Manage AI-generated suggestions for shared models
  - name: AI Routines
    description: >-
      Manage AI Routines: schedule recurring AI-powered tasks to run
      automatically on your data.
  - name: Documents v2
    description: >
      A draft-based workflow for creating and editing documents: create a
      document, patch a draft, then publish. Replaces the one-shot `PUT`/`PATCH`
      v1 document write endpoints.
  - name: Documents
    description: Create, retrieve, and manage documents
  - 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: 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:
  /v2/documents/{documentId}/draft/{draftId}:
    get:
      tags:
        - Documents v2
      summary: Get draft state
      description: >
        Read the named draft's state. Returns the same `DocumentsV2ReadResponse`
        shape as [Get document state](/api/documents-v2/get-document-state), and
        is round-trippable as a `PATCH` body.
      operationId: documentsV2GetDraft
      parameters:
        - name: documentId
          in: path
          required: true
          schema:
            type: string
          description: >-
            The published document's URL slug (e.g. `abc123`) or its canonical
            workbook UUID.
        - name: draftId
          in: path
          required: true
          schema:
            type: string
          description: >-
            The draft workbook identifier (returned by [Create draft and patch
            document](/api/documents-v2/create-draft-and-patch-document)).
        - name: pretty
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            Format response with 2-space indentation for readability. Accepts
            `true`, `1`, or no value (e.g., `?pretty`). Default is compact
            (single-line) JSON.
      responses:
        '200':
          description: Draft state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentsV2ReadResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions to read the draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Document or draft not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >
            The draft cannot be read as a dashboard: a classic-layout dashboard
            (upgrade to the advanced layout first) or an app document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    DocumentsV2ReadResponse:
      type: object
      required:
        - description
        - name
        - queryPresentations
      description: >
        Current document (or draft) state. Round-trippable: submit this verbatim
        as a draft `PATCH` body. `containers`, `controls`, and `settings` are
        dashboard-scoped and omitted for workbook-only documents with no layout
        yet.
      properties:
        name:
          type: string
          maxLength: 254
          description: Document name.
        description:
          type:
            - string
            - 'null'
          description: Document description.
        queryPresentations:
          $ref: '#/components/schemas/DocumentsV2QueryPresentationsRead'
        controls:
          $ref: '#/components/schemas/DocumentsV2ControlsRead'
        settings:
          $ref: '#/components/schemas/DocumentsV2SettingsRead'
        containers:
          $ref: '#/components/schemas/DocumentsV2Containers'
    Error:
      type: object
      properties:
        error:
          type: string
          description: HTTP response code for the error
          example: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
    DocumentsV2QueryPresentationsRead:
      type: object
      required:
        - data
        - order
      properties:
        data:
          type: object
          description: Tabs keyed by record key (a positive-integer string).
          additionalProperties:
            $ref: '#/components/schemas/DocumentsV2QueryPresentation'
        order:
          type: array
          description: Tab display order.
          items:
            type: string
            pattern: ^[1-9][0-9]*$
    DocumentsV2ControlsRead:
      type: object
      required:
        - data
        - order
      properties:
        data:
          type: object
          description: Controls keyed by control ID.
          additionalProperties:
            $ref: '#/components/schemas/DocumentsV2Control'
        order:
          type: array
          description: Display order for controls.
          items:
            type: string
    DocumentsV2SettingsRead:
      type: object
      required:
        - crossfilterEnabled
        - customText
        - facetFilters
        - refreshInterval
        - runQueriesOn
      properties:
        crossfilterEnabled:
          type: boolean
          description: >-
            When true, clicking a value in one tile filters all other tiles on
            the dashboard.
        customText:
          type:
            - object
            - 'null'
          description: Custom text replacing default UI strings on the dashboard.
          properties:
            queryError:
              type: string
            queryNoResults:
              type: string
        facetFilters:
          type: boolean
          description: >-
            When true, dashboard filters are applied per-facet when faceting is
            active.
        refreshInterval:
          type:
            - number
            - 'null'
          description: Auto-refresh interval in seconds. Null disables auto-refresh.
        runQueriesOn:
          type:
            - string
            - 'null'
          enum:
            - current-page
            - all-pages
            - null
          description: >-
            Controls whether dashboard queries execute on the visible page or
            across all pages.
    DocumentsV2Containers:
      type: array
      description: >
        Container layout array (grid / stack / page / reference containers,
        recursively nested). On a patch, when present this **fully replaces**
        the existing layout. The server validates the full structure on apply;
        container `instanceKey` / `referenceKey` values round-trip unchanged.
        See the dashboard layout reference for the complete grammar.
      items:
        type: object
        additionalProperties: true
    DocumentsV2QueryPresentation:
      type: object
      required:
        - type
      description: >
        A single tab/tile. The server owns internal tile identity — callers
        never send `miniUuid`; tiles are addressed by their record key in
        `queryPresentations.data`.
      properties:
        type:
          type: string
          enum:
            - blank
            - csv
            - query
            - dataset
            - spreadsheet
            - sql
            - dbt
            - query-view
            - linked
            - app
          description: >-
            The query presentation type. `query` is a semantic query; `sql` is
            raw SQL; `linked` reuses another tile's query (see
            `sourceQueryPresentationKey`).
        name:
          type: string
          minLength: 1
          maxLength: 144
          description: User-provided tab name.
        subTitle:
          type:
            - string
            - 'null'
          maxLength: 250
          description: User-provided tab subtitle.
        description:
          type:
            - string
            - 'null'
          maxLength: 500
          description: User-provided tab description.
        sourceQueryPresentationKey:
          type:
            - string
            - 'null'
          pattern: ^[1-9][0-9]*$
          description: >
            For `linked`-type tabs, the record key — the same identifier used as
            a `queryPresentations.data` key — of the source tile whose query
            this tab reuses. Null for all other tab types. This is a tile record
            key, **not** a positional index into `order`.
        topicName:
          type:
            - string
            - 'null'
          description: The topic (explore) this query is built on.
        isSql:
          type:
            - boolean
            - 'null'
          description: Whether this tab is in raw SQL mode.
        prefersChart:
          type: boolean
          description: >-
            When true, the chart view is shown by default instead of the data
            table.
        automaticVis:
          type:
            - boolean
            - 'null'
          description: >-
            When true, the system automatically selects the best visualization
            type.
        filterOrder:
          type: array
          items:
            type: string
          description: >-
            Ordered list of filter field names controlling display order on this
            tab.
        editingModelObjectName:
          type:
            - string
            - 'null'
          description: >-
            Model object (view/topic) currently being edited via the
            dataset/query-view editor. Applies only to `dataset` / `query-view`
            tabs — omitted from reads and rejected on patches for other tab
            types.
        editingModelObjectNameChange:
          type:
            - string
            - 'null'
          description: >-
            Pending rename of the model object being edited. Applies only to
            `dataset` / `query-view` tabs — omitted from reads and rejected on
            patches for other tab types.
        query:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: >-
            The semantic query for this tab (fields, filters, sorts, limits,
            etc.), minus the server-owned workbook model anchors. Omitted on a
            no-op replay; the server anchors new/changed tiles to the draft.
        visConfig:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: Visualization configuration for the tile.
        resultConfig:
          type: object
          additionalProperties: true
          description: >-
            Result display configuration (column widths, frozen columns,
            conditional formatting, number formatting, etc.).
        aiConfig:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: >-
            AI-generated metadata config (subtitle/description auto-generation
            settings).
    DocumentsV2Control:
      type: object
      additionalProperties: true
      description: >
        A dashboard control (filter). The full config grammar — control type,
        field bindings, filter values, and (for multi-field filters) the
        recursive composite-filter grammar — is validated by the server on
        apply. See the dashboard filters & controls reference for the complete
        structure.
  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#token-types).


        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`

````