Create, rename, rewrite, or delete canvases (collaborative Markdown documents). Use `action=replaceContent` with the `If-Match` ETag from getCanvasContent to rewrite the body; use `update` for title or workspace access only. To read a canvas, use getCanvas or getCanvasContent. Set `action` to one of: create, delete, replaceContent, update. Then provide the fields for the selected action. action=create: Create a new canvas, optionally seeded with Markdown or from a template. Use this when the user wants a new document to write or collaborate in. `title` is required (1–255 chars). Supply either `content` (Markdown) or `template_id`; when a template is given, `content` is ignored and the caller must be able to read the template (else 404 `template_not_found`). `workspace_canvas_role` defaults to `NOACCESS`; `VIEWER` shares read access with the whole workspace. The 201 body includes the canvas plus the initial `etag` for a first v1UpdateCanvasContent. Send an `Idempotency-Key` to avoid duplicates on retry. 402 means the plan lacks canvases; 422 means the Markdown could not be converted. action=delete: Delete a canvas the user owns. Use this only when the user explicitly wants a canvas removed. Soft-deletes the canvas row and best-effort removes the collaborative document. Owner only: any non-owner who can see the canvas (editor or viewer) gets 403; unknown or inaccessible canvases get 404. Returns 204; a repeat delete 404s, so retries are safe. There is no restore through this API. action=replaceContent: Replace the entire body of a canvas with new Markdown, guarded by the ETag from the last read. Use this to rewrite a canvas after reading it with getCanvasContent. Full replacement, not a patch: send the complete new body in `content` (non-empty; use v1DeleteCanvas to remove a canvas). `If-Match` is required and must be the `etag` from v1GetCanvasContent or a prior write — missing gives 400 `checksum_required`; stale gives 409 `checksum_mismatch` with the current ETag in the `ETag` header. On 409, re-read the content, re-apply the user's intent to the fresh body, and retry once with the new ETag; never merge blindly. The 200 body carries the new `etag` for the next write. Requires editor access; viewers get 404. 422 means the Markdown could not be converted. action=update: Rename a canvas or change its workspace-wide access. Use this for metadata changes; to change the body, use the replaceContent action. Partial update (PATCH) of `title` (1–255 chars) and/or `workspace_canvas_role` (`VIEWER` or `NOACCESS`); at least one is required. Scalar last-writer-wins — no `If-Match` is needed and the body is untouched. Requires editor access; viewers and unknown canvases return 404. 402 means the plan lacks canvases.
manageCanvasesCreate, rename, rewrite, or delete canvases (collaborative Markdown documents). Use action=replaceContent with the If-Match ETag from getCanvasContent to rewrite the body; use update for title or workspace access only. To read a canvas, use getCanvas or getCanvasContent.
Set action to one of: create, delete, replaceContent, update. Then provide the fields for the selected action.
action=create: Create a new canvas, optionally seeded with Markdown or from a template. Use this when the user wants a new document to write or collaborate in.
title is required (1–255 chars). Supply either content (Markdown) or template_id; when a template is given, content is ignored and the caller must be able to read the template (else 404 template_not_found). workspace_canvas_role defaults to NOACCESS; VIEWER shares read access with the whole workspace. The 201 body includes the canvas plus the initial etag for a first v1UpdateCanvasContent. Send an Idempotency-Key to avoid duplicates on retry. 402 means the plan lacks canvases; 422 means the Markdown could not be converted.
action=delete: Delete a canvas the user owns. Use this only when the user explicitly wants a canvas removed.
Soft-deletes the canvas row and best-effort removes the collaborative document. Owner only: any non-owner who can see the canvas (editor or viewer) gets 403; unknown or inaccessible canvases get 404. Returns 204; a repeat delete 404s, so retries are safe. There is no restore through this API.
action=replaceContent: Replace the entire body of a canvas with new Markdown, guarded by the ETag from the last read. Use this to rewrite a canvas after reading it with getCanvasContent.
Full replacement, not a patch: send the complete new body in content (non-empty; use v1DeleteCanvas to remove a canvas). If-Match is required and must be the etag from v1GetCanvasContent or a prior write — missing gives 400 checksum_required; stale gives 409 checksum_mismatch with the current ETag in the ETag header. On 409, re-read the content, re-apply the user's intent to the fresh body, and retry once with the new ETag; never merge blindly. The 200 body carries the new etag for the next write. Requires editor access; viewers get 404. 422 means the Markdown could not be converted.
action=update: Rename a canvas or change its workspace-wide access. Use this for metadata changes; to change the body, use the replaceContent action.
Partial update (PATCH) of title (1–255 chars) and/or workspace_canvas_role (VIEWER or NOACCESS); at least one is required. Scalar last-writer-wins — no If-Match is needed and the body is untouched. Requires editor access; viewers and unknown canvases return 404. 402 means the plan lacks canvases.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Canvas ID | |
| title | No | Canvas title (1-255 characters) | |
| action | Yes | The operation to perform | |
| content | No | Initial body in Markdown. Ignored when template_id is supplied, since the template provides the body. | |
| If-Match | No | ETag of the body the replacement was authored against | |
| template_id | No | Canvas template to instantiate. The caller must be able to read the template. | |
| Idempotency-Key | No | Optional client-generated idempotency key (max 255 printable ASCII). Repeat requests with the same key replay the original 2xx response. | |
| workspace_canvas_role | No | Access for workspace members who are not explicit collaborators: VIEWER or NOACCESS (default NOACCESS) |