---
title: "Replace app content on a draft"
method: PUT
path: "/v2/documents/{documentId}/draft/{draftId}/app"
tags: ["Apps"]
---

# Replace app content on a draft

`PUT /v2/documents/{documentId}/draft/{draftId}/app`

## Request

- Base URL: `https://blobsrus.omniapp.co/api`
- URL: `https://blobsrus.omniapp.co/api/v2/documents/{documentId}/draft/{draftId}/app`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

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

Replace the app HTML on an existing draft. If the specified document does not yet have an app, one will be created.

## Path parameters

- `draftId` string, required
- `documentId` string, required

## Request body

- AppPutBody
  - `html` string, required: The complete app HTML document. Replaces the current HTML; capped at 2 MiB of UTF-8. `maxLength` counts characters — the byte cap is what the server enforces. Every write appends an immutable revision.
  - `settings` object: When present, replaces the app settings; omitted fields take their locked-down defaults. When absent, the current settings are retained.
    - `allowClipboard` boolean: Allow the app to read from and write to the user's clipboard.
    - `allowDefaultMapProviders` boolean: Allow the app to load Omni's default map tile providers.
    - `allowDownloads` boolean: Allow the app to trigger file downloads.
    - `allowExternalNavigation` boolean: Allow the app to navigate to domains outside the `navAllowedDomains` / `safeDomains` allowlists.
    - `allowFullscreen` boolean: Allow the app to enter full screen via `requestFullscreen()` (e.g. a "Present" button).
    - `allowInternalNavigation` boolean: Allow the app to navigate within the Omni instance.
    - `externalNavOpensInNewTab` boolean: When true, external navigation opens in a new tab instead of the current one.
    - `navAllowedDomains` string[]: Domains the app is allowed to navigate to when `navAllowedDomainsEnabled` is true.
    - `navAllowedDomainsEnabled` boolean: When true, restrict navigation to the domains listed in `navAllowedDomains`.
    - `safeDomains` string[]: Domains treated as safe for embedded content when `safeDomainsEnabled` is true.
    - `safeDomainsEnabled` boolean: When true, restrict embedded content to the domains listed in `safeDomains`.

## Response `200`

App written on the draft.

- AppPutResponse
  - `identifier` string, required: Published document identifier the draft targets.
  - `draftIdentifier` string, required: Identifier of the draft the patch was applied to.
  - `name` string, required: Document name.
  - `description` string, nullable, required: Document description.
  - `app` AppState, required
    - `settings` AppSettings, required: 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.
      - `allowClipboard` boolean: Allow the app to read from and write to the user's clipboard.
      - `allowDefaultMapProviders` boolean: Allow the app to load Omni's default map tile providers.
      - `allowDownloads` boolean: Allow the app to trigger file downloads.
      - `allowExternalNavigation` boolean: Allow the app to navigate to domains outside the `navAllowedDomains` / `safeDomains` allowlists.
      - `allowFullscreen` boolean: Allow the app to enter full screen via `requestFullscreen()` (e.g. a "Present" button).
      - `allowInternalNavigation` boolean: Allow the app to navigate within the Omni instance.
      - `externalNavOpensInNewTab` boolean: When true, external navigation opens in a new tab instead of the current one.
      - `navAllowedDomains` string[]: Domains the app is allowed to navigate to when `navAllowedDomainsEnabled` is true.
      - `navAllowedDomainsEnabled` boolean: When true, restrict navigation to the domains listed in `navAllowedDomains`.
      - `safeDomains` string[]: Domains treated as safe for embedded content when `safeDomainsEnabled` is true.
      - `safeDomainsEnabled` boolean: When true, restrict embedded content to the domains listed in `safeDomains`.
  - `warnings` string[]: Included only when non-blocking warnings are encountered when creating/updating an app. The write itself succeeded.

## Other responses

- `400`: Invalid request body (unknown field, empty, or `html` exceeds the cap of 2 MiB).
- `401`: Authentication required.
- `403`: Insufficient permissions: no write access to the document, apps not enabled for the organization, or (user-scoped keys) the role does not allow creating apps.
- `404`: Document or draft not found. Also returned when `documentId` names a draft rather than a published document — drafts only attach to published documents.
- `405`: Method not allowed.
- `422`: The draft is a dashboard, not an app; remove the dashboard with the [Remove dashboard from document API](/api/documents/remove-dashboard-from-document).

## Changes

- **2026-11-03** `43290040f88f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omni/apis/omni-api/changes/v2/documents/:documentId/draft/:draftId/app/put.md)

---

[API](https://skmtc.dev/omni/apis/omni-api.md) - [All operations](https://skmtc.dev/omni/apis/omni-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omni/apis/omni-api/revisions/43290040f88f?raw)