--- title: "Edit app content on a draft" method: PATCH path: "/v2/documents/{documentId}/draft/{draftId}/app" tags: ["Apps"] --- # Edit app content on a draft `PATCH /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 This API is currently in development and may change. Apply targeted changes to an existing app on an existing draft without resending the HTML. Changes are all or nothing — an edit that matches zero times, matches more than once without `replaceAll`, or would push the HTML past the 2 MiB cap rejects the whole request with 400 naming the edit, and nothing is applied. This endpoint does not create an app. Use the `draftIdentifier` in the response to call the [Publish draft API](/api/documents-v2/publish-draft) and publish the changes. ## Path parameters - `draftId` string, required - `documentId` string, required ## Request body - union - object - `htmlEdits` AppHtmlEdit[], required: 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. - `replace` string, required: Text that replaces the matched `search` text. May be empty (deletion). - `replaceAll` boolean: Replace every occurrence of `search` instead of requiring a unique match. - `search` string, required: Exact substring of the app's current HTML, copied with enough surrounding context to be unique unless `replaceAll: true`. - `settings` object: When present, replaces the app settings; omitted fields take their locked-down defaults. When absent, the current settings are kept. - `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`. - object - `htmlEdits` AppHtmlEdit[]: 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. - `replace` string, required: Text that replaces the matched `search` text. May be empty (deletion). - `replaceAll` boolean: Replace every occurrence of `search` instead of requiring a unique match. - `search` string, required: Exact substring of the app's current HTML, copied with enough surrounding context to be unique unless `replaceAll: true`. - `settings` object, required: When present, replaces the app settings; omitted fields take their locked-down defaults. When absent, the current settings are kept. - `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` Edits applied on the draft. `warnings` names any resource hosts the app’s iframe CSP will block until an Organization Admin allows them, and navigation domains the organization’s navigation policy refuses. - AppWriteResponse - `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, 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. - `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. - `409`: The draft has no app to patch. - `422`: The draft is a dashboard, not an app. ## 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/patch.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)