Sign in
Documents

Create-or-reuse the draft and replace app content

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

Create (or reuse) the document's main draft and replace the app on it in one call — the app-side counterpart of PATCH …/draft's create-or-reuse behavior, with the same body, validation, and gates as PUT …/draft/{draftIdentifier}/app. No auto-publish; the response carries the draftIdentifier for POST …/draft/publish. Removing the app has no create-or-reuse counterpart — DELETE stays draft-explicit.

Last-write-wins, like every app write in the UI: the body is applied as given, with no expected-version precondition.

app is a reserved literal under …/draft/ — the router ranks it above the dynamic {draftIdentifier} segment. A draft named app would be unaddressable on the draft-scoped app routes; avoid 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/app

Path parameters

identifierstring required

Document identifier — either the URL slug (e.g. abc123) or the canonical workbook UUID.

Example:abc123

Document identifier — either the URL slug (e.g. abc123) or the canonical workbook UUID.

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

Draft created (or reused) and app written; the response carries the draftIdentifier. 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