Documents

Replace app content on a draft

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

Replace the app HTML on an existing draft — creating the app when the draft is workbook-only — optionally replacing the app settings in the same call. Operates only on the draft named by draftIdentifier, which the caller creates first via PATCH …/draft; a published app is never addressable for writing, so every edit is draft-then-publish by construction. No auto-publish — publish via POST …/draft/publish.

Last-write-wins, like every app write in the UI: the body is applied as given, with no expected-version precondition. Every write appends an immutable app_history revision, so nothing is lost — only the head moves.

Writes never reject on host policy. External <script src> / <link rel="stylesheet"> hosts outside the organization’s app policy (resolved over the settings this write produces) come back as non-blocking warnings — the render-time CSP is the enforcement, and a disallowed host is inert until an org admin allows it.

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.

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

Path parameters

draftIdentifierstring required

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

Example:def456

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

identifierstring required

Published document identifier.

Example:abc123

Published document identifier.

Request body

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

Response

App written 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. The write itself succeeded.

Changes