Documents

Edit app content on a draft

Changed on

Alpha. The app sub-resource may change shape without a deprecation cycle while apps mature. The document routes are stable.

Apply targeted edits to the app on an existing draft without resending the HTML body: any subset of htmlEdits (exact-substring search/replace operations, applied in order) and settings (full replacement). 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.

Content addressing buys sequential staleness detection, not concurrency safety: if the text an edit targets moved between your read and your write, the edit fails to match and nothing is applied. There is no version precondition, compare-and-swap, or lock behind it, so two writers patching the same app at the same time can still overwrite each other, orthogonal edits included — serialize writes to one app when that matters. PATCH never creates the app: a draft with no app is a 409 (create it with PUT).

A document carries at most one of a dashboard or an app — never both; workbook-only is valid. The app HTML and settings live only at the app sub-resource routes; the document read carries an app slice pointing here, and the whole-document PATCH accepts that slice back only as it was read.

patch/api/v2/documents/{identifier}/draft/{draftIdentifier}/app

Request

  • Base URL
    https://omniapp.co (the document declares no server; this is the origin it was published from)
  • URL
    https://omniapp.co/api/v2/documents/{identifier}/draft/{draftIdentifier}/app
  • Auth
    HTTP bearer

Path parameters

draftIdentifierstring required

Draft workbook identifier (see PATCH /api/v2/documents/{identifier}/draft).

Example:def456
identifierstring required

Published document identifier.

Example:abc123

Request body

OR

Response

Edits applied on the draft. warnings names any resource hosts the app’s iframe CSP will block until an org admin allows them.

descriptionstring nullable required

Document description.

draftIdentifierstring required

Identifier of the draft the patch was applied to.

identifierstring required

Published document identifier the draft targets.

namestring required

Document name.

warningsstring[]

Non-blocking warnings — present only when there are any. Currently: external resource hosts the app's iframe CSP will block until an org admin allows them, a map-provider, print-and-dialogs, fullscreen, clipboard, or downloads setting the organization's app policy turns off for every app, and navigation domains outside the organization's navigation policy (links to them are refused). The write itself succeeded. Advisory prose, not a contract: the wording is deliberately volatile, there are no per-warning codes, and consumers must not branch on the content. The render-time CSP is the enforcement.

Changes

    • info

      added the new optional request property /////

    • info

      added the optional property /// to the response with the status

    • info

      api operation id documentsV2PatchApp removed and replaced with documentsPatchApp