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

# Create/reuse draft and edit app content

> <Note>
  This API is currently in development and may change.
</Note>

Create or reuse an existing document's main draft and apply targeted edits to the app's HTML without resending the whole document.



## OpenAPI

````yaml /api/openapi.yaml patch /v2/documents/{documentId}/draft/app
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 Credit Usage
    description: Monitor AI credit usage
  - name: AI Evals
    description: >-
      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 Routines, which are scheduled, recurring AI-powered tasks that run
      automatically on your data
  - name: Apps
    description: Draft and publish app documents.
  - name: Documents v2
    description: >
      A draft-based workflow for creating and editing documents: create a
      document, patch a draft, then publish.
  - name: Documents
    description: Create, retrieve, and manage documents
  - name: API Tokens
    description: >-
      Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
      grants)
  - name: IP Allowlist
    description: Manage the organization's IP allowlist
  - name: Connections
    description: Manage database connections
  - name: Connection environments
    description: Manage connection environments database connections
  - name: Color Palettes
    description: Manage custom chart color palettes
  - 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: Embed
    description: Manage embed sessions
  - name: Labels
    description: |
      Manage labels in the organization
  - name: Folders
    description: Create and organize content folders
  - name: Folder labels
    description: Apply and manage labels on 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: Skills
    description: >-
      Manage skills, the saved slash-command instructions the Omni AI assistant
      runs
  - 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/app:
    patch:
      tags:
        - Apps
      summary: Create/reuse draft and edit app content
      description: >-
        <Note>
          This API is currently in development and may change.
        </Note>


        Create or reuse an existing document's main draft and apply targeted
        edits to the app's HTML without resending the whole document.
      operationId: documentsPatchAppAutoDraft
      parameters:
        - name: documentId
          schema:
            type: string
            description: >-
              Document identifier — either the URL slug (e.g. `abc123`) or the
              canonical workbook UUID.
            example: abc123
          required: true
          description: >-
            Document identifier — either the URL slug (e.g. `abc123`) or the
            canonical workbook UUID.
          in: path
        - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppPatchBody'
      responses:
        '200':
          description: >-
            Draft created or reused and edits applied. Use the `draftIdentifier`
            in the response to call the [Publish draft
            API](/api/documents-v2/publish-draft) and publish the changes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppPutResponse'
        '400':
          description: >
            Invalid request body (unknown field, neither `htmlEdits` nor
            `settings`, or more than 20 `htmlEdits`), or a failed `htmlEdits`
            entry (not found, ambiguous, or result over the 2 MiB cap). Nothing
            is applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError400'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError401'
        '403':
          description: >
            Insufficient permissions: no write access to the document, apps not
            enabled for the organization, or (a user-scoped key, or an
            organization key acting as `userId`) the role does not allow
            creating apps. Also returned when a user-scoped key passes `userId`
            naming a different member, or when `userId` names an embed user with
            no live embed session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError403'
        '404':
          description: >-
            Document not found, `userId` names a membership outside the
            organization, or `userId` names a member who hasn't accepted their
            invitation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: There is no app to patch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The document is a dashboard, not an app.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    userId:
      name: userId
      schema:
        type: string
        format: uuid
      required: false
      description: >
        **Organization API key required.** The membership ID of the user to act
        as.
      in: query
  schemas:
    AppPatchBody:
      type: object
      properties:
        htmlEdits:
          type: array
          items:
            $ref: '#/components/schemas/AppHtmlEdit'
          minItems: 1
          maxItems: 20
          description: >
            Targeted edits applied in order against the current HTML. A failed
            edit (not found, ambiguous, or result over the 2 MiB cap) rejects
            the entire request with 400 naming the edit. At most 20 edits per
            request.
        settings:
          allOf:
            - $ref: '#/components/schemas/AppSettings'
            - description: >-
                When present, replaces the app settings; omitted fields take
                their locked-down defaults. When absent, the current settings
                are kept.
      additionalProperties: false
      anyOf:
        - required:
            - htmlEdits
        - required:
            - settings
    AppPutResponse:
      allOf:
        - $ref: '#/components/schemas/DocumentsV2PatchDraftResponse'
        - type: object
          properties:
            app:
              $ref: '#/components/schemas/AppState'
            warnings:
              $ref: '#/components/schemas/AppWarnings'
          required:
            - app
    ApiError400:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 400
      required:
        - detail
        - status
    ApiError401:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
          example: 'Unauthorized: Missing or invalid API key'
        status:
          type: integer
          description: HTTP status code of the error.
          example: 401
      required:
        - detail
        - status
    ApiError403:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 403
      required:
        - detail
        - status
    ApiError404:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 404
      required:
        - detail
        - status
    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>
    AppHtmlEdit:
      type: object
      required:
        - replace
        - search
      properties:
        replace:
          type: string
          description: >-
            Text that replaces the matched `search` text. May be empty
            (deletion).
        replaceAll:
          type: boolean
          description: >-
            Replace every occurrence of `search` instead of requiring a unique
            match.
        search:
          type: string
          minLength: 1
          description: >
            Exact substring of the app's current HTML, copied with enough
            surrounding context to be unique unless `replaceAll: true`.
      additionalProperties: false
    AppSettings:
      type: object
      additionalProperties: false
      description: >
        The app's sandbox settings. A write replaces the whole object; omitted
        fields use their locked-down defaults. Host lists are normalized
        (deduped, invalid or Omni-owned hosts dropped) before they are stored.
      properties:
        allowClipboard:
          type: boolean
          default: false
          description: Allow the app to read from and write to the user's clipboard.
        allowDefaultMapProviders:
          type: boolean
          default: false
          description: Allow the app to load Omni's default map tile providers.
        allowDownloads:
          type: boolean
          default: false
          description: Allow the app to trigger file downloads.
        allowExternalNavigation:
          type: boolean
          default: false
          description: >-
            Allow the app to navigate to domains outside the `navAllowedDomains`
            / `safeDomains` allowlists.
        allowFullscreen:
          type: boolean
          default: false
          description: >-
            Allow the app to enter full screen via `requestFullscreen()` (e.g. a
            "Present" button).
        allowInternalNavigation:
          type: boolean
          default: false
          description: Allow the app to navigate within the Omni instance.
        externalNavOpensInNewTab:
          type: boolean
          default: true
          description: >-
            When true, external navigation opens in a new tab instead of the
            current one.
        navAllowedDomains:
          type: array
          items:
            type: string
          default: []
          description: >-
            Domains the app is allowed to navigate to when
            `navAllowedDomainsEnabled` is true.
        navAllowedDomainsEnabled:
          type: boolean
          default: false
          description: >-
            When true, restrict navigation to the domains listed in
            `navAllowedDomains`.
        safeDomains:
          type: array
          items:
            type: string
          default: []
          description: >-
            Domains treated as safe for embedded content when
            `safeDomainsEnabled` is true.
        safeDomainsEnabled:
          type: boolean
          default: false
          description: >-
            When true, restrict embedded content to the domains listed in
            `safeDomains`.
    DocumentsV2PatchDraftResponse:
      type: object
      required:
        - description
        - draftIdentifier
        - identifier
        - name
      properties:
        identifier:
          type: string
          description: Published document identifier the draft targets.
          example: def456
        draftIdentifier:
          type: string
          description: Identifier of the draft the patch was applied to.
          example: abc123
        name:
          type: string
          description: Document name.
          example: Blob Sales
        description:
          type:
            - string
            - 'null'
          description: Document description.
          example: Overview of daily Blobs R Us Sales
    AppState:
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/AppSettings'
      required:
        - settings
    AppWarnings:
      type: array
      items:
        type: string
      description: >
        Included only when non-blocking warnings are encountered when
        creating/updating an app. Currently, external resource hosts the app's
        iframe CSP will block until an Organization Admin allows them. The write
        itself succeeded.
  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`

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.