PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub

API

Task description content

Stored Plate JSON contract — canonical field, allowed nodes, security, and write rules.

Task descriptions are a Plate rich-text document, not a markdown string. The in-app editor, REST (/api/v1), and MCP (planeward-task-*) share one store and one validator.

Canonical field

ColumnTypeRole
descriptionContentJSON array or nullSource of truth. What the editor persists.
descriptionstring or nullDerived plain text for search and API consumers. The editor does not write this column.

descriptionContent: null (or omit on create) is an empty description. An empty document serializes to null.

Write rules (REST and MCP)

  1. descriptionContent wins. When it is present, description is ignored and the stored plain-text field is derived from the document.
  2. Plain description only when content is omitted. Each non-empty line becomes a paragraph node (type: "p").
  3. Sending descriptionContent: null clears both fields.
  4. The server normalizes node ids. Clients do not need to generate them.
  5. Invalid documents are rejected. The API does not strip unknown types or unsafe URLs.

Document shape

The document is a JSON array of element nodes (Plate Value).

[
  {
    "id": "p1",
    "type": "p",
    "children": [{ "text": "Hello", "bold": true }]
  }
]
  • Elements have type and children.
  • Text leaves have a text string. Marks are booleans on the leaf (bold, italic, underline, strikethrough, highlight).
  • Void nodes (hr, img, video, file, media_embed, link_preview) still include children: [{ "text": "" }].
  • Extra properties on allowed types are kept (Plate adds indent, table spans, and similar). __proto__, prototype, and constructor are rejected.

Allowed element types

These match the in-app task editor. Any other type is rejected (script, iframe, blockquote, h4, …).

TypeKind
pParagraph. Also used for lists (see below).
h1 h2 h3Headings
hrHorizontal rule
aInline link. url required.
code_block code_line code_syntaxFenced code
table tr td thTables
img video fileWorkspace media
media_embedYouTube / Vimeo only
link_previewUnfurled URL card

Lists are not wrapper nodes. A list item is a paragraph (or heading) with indent (integer 0–24) and listStyleType:

{
  "type": "p",
  "indent": 1,
  "listStyleType": "disc",
  "children": [{ "text": "Item" }]
}

Allowed listStyleType values: disc, circle, square, decimal, decimal-leading-zero, lower-alpha, upper-alpha, lower-roman, upper-roman, todo. Checklist items may set checked (boolean). Ordered lists may set listStart (integer ≥ 1).

Media and attachments

Workspace uploads store references, not file bytes, in the document:

{
  "type": "file",
  "attachmentId": "…",
  "fileAssetId": "…",
  "name": "brief.pdf",
  "mimeType": "application/pdf",
  "url": "",
  "children": [{ "text": "" }]
}
  • url may be "" when attachmentId / fileAssetId point at workspace files. The product editor writes it that way.
  • A non-empty url on img, video, or file must be https with no credentials. data:, javascript:, and http are rejected.
  • media_embed.url must be https on youtube.com, www.youtube.com, youtube-nocookie.com, www.youtube-nocookie.com, vimeo.com, or player.vimeo.com.

The public API does not upload files. Referencing attachmentId values you did not create in this workspace will not attach a downloadable file.

Platform announcements (staff /admin/announcements, not task API) reuse the same Plate shape. Inline images may set platformImageKey to an object under platform/announcements/<announcementId>/ in the images bucket; url is cleared on save and filled at display time. This field is announcement-only.

Link previews

{
  "type": "link_preview",
  "url": "https://example.com/post",
  "title": "Example",
  "description": "…",
  "siteName": "Example",
  "imageObjectKey": "workspaces/<workspaceId>/link-previews/<64-hex>.png",
  "faviconObjectKey": null,
  "fetchedAt": "2026-08-25T00:00:00.000Z",
  "children": [{ "text": "" }]
}
  • url is https only. The server refuses private, loopback, link-local, and credentialed hosts (SSRF protection).
  • imageUrl and faviconUrl are not allowed. Preview images are object keys under workspaces/<workspaceId>/link-previews/ only.
  • Title / description / site name are length-capped.

Hyperlinks

a.url must be http or https with no credentials. javascript:, data:, vbscript:, and file: are rejected.

Size and integrity limits

LimitValue
Serialized JSON100,000 characters
Nodes (walk of the tree)2,500
Nesting depth16
Children per node500
Characters per text leaf20,000
URL length2,048

The document must be a JSON array. Objects, strings, and non-object nodes are rejected.

Minimal examples

Paragraphs from plain text (description only):

[{ "type": "p", "children": [{ "text": "Ship the invoice flow." }] }]

Clear the description:

{ "descriptionContent": null }

Embedded projects

Secure iframe embed so host-site users can create and manage their own partitioned projects.

Developer hub

Create an API key, register a webhook, or connect MCP.

On this page

Canonical fieldWrite rules (REST and MCP)Document shapeAllowed element typesMedia and attachmentsLink previewsHyperlinksSize and integrity limitsMinimal examples