Fire action by ID

Fires a workflow action, specified by identifier, on a target contentlet.

Returns a map of the resultant contentlet, with an additional AUTO_ASSIGN_WORKFLOW property, which can be referenced by delegate services that handle automatically assigning workflow schemes to content with none.

Use this endpoint to fire actions that are not represented as SystemAction tokens (NEW, EDIT, PUBLISH, etc.). The two most common are Move and Copy on the System Workflow scheme.

Move action — relocates a contentlet to a new folder/host. Request body shape (note: pathToMove is a sibling of contentlet, not nested inside it):

{
  "contentlet": { "identifier": "<contentlet-identifier>" },
  "pathToMove": "//<siteHost>/<folderPath>"
}

Alternative shapes (contentlet.host+contentlet.folder, contentlet.hostFolder, path instead of pathToMove) all return 400 "The host path is not valid: null".

Copy action — clones a contentlet. Fire with ?identifier=<source-id> and an empty body (or {"contentlet": {"identifier": "<source-id>"}}). The Copy action id on the default System Workflow scheme is 963f6a04-5320-42e7-ab74-6d876d199946; retrieve it for other environments via GET /api/v1/workflow/schemes/{schemeId}/actions. ⚠️ The response entity returns the source contentlet, not the newly-created copy — locate the copy via a follow-up POST /api/content/_search ordered by modDate DESC. The copy lands in SYSTEM_HOST / SYSTEM_FOLDER; destination hints (pathToMove, host, folder, hostFolder) are silently ignored. Fire the Move action afterwards to relocate.

When chaining workflow actions or reading state back immediately after firing, pass indexPolicy=WAIT_FOR on each call. The default DEFER is asynchronous and can return stale index reads for several seconds, which can mimic server-side state bugs. For isolated one-off fires where nothing reads the result, leave the default.

Block Editor (Story Block) fields: send the value as a Markdown or HTML string — you do not need to hand-author the underlying ProseMirror/JSON document. dotCMS converts it to the Block Editor (ProseMirror JSON) structure automatically on save, so the field reads back as structured content with no editor round-trip required. A value that is already a valid Tiptap/ProseMirror JSON document is detected and stored unchanged. Example: "body": "## Intro\n\nHello **world**.".

Rich blocks in Markdown: blocks that plain Markdown cannot express are written as fenced code blocks whose info string is a dotcms-* label and whose body is a small JSON object. Example — embed a contentlet:

dotcms-content\n{"identifier": "<contentlet-id>", "languageId": 1}\n

Supported labels and payload fields (bold = required):

• dotcms-content → embedded contentlet: identifier, languageId (default 1). The server rebuilds the full embed data from the identifier on every read.
• dotcms-image → dotCMS-bound or decorated image: identifier or src; optional alt, title, href, target, textWrap, textAlign, languageId. Plain external images need no fence — standard  works.
• dotcms-video → video: identifier or src; optional mimeType, width, height, languageId.
• dotcms-youtube → YouTube embed: src; optional start (seconds), width, height.
• dotcms-grid → layout grid: the verbatim gridBlock node JSON ({"type":"gridBlock","attrs":{"columns":[n,n]},"content":[…two gridColumn nodes…]}).
• dotcms-node → any other node type verbatim ({"type": "<nodeType>", …}) — the fallback for custom blocks.

Rich blocks in HTML: the same labels are namespaced custom elements. Scalar payloads ride as attributes with hyphenated names (HTML lowercases attribute names, so languageId is spelled language-id, mimeType is mime-type): <dotcms-content identifier="<contentlet-id>" language-id="1"></dotcms-content>. dotcms-ai, dotcms-grid and dotcms-node take the same JSON object as the element's text body instead (HTML-escape < and & inside JSON string values). Always write an explicit closing tag — HTML parsing ignores the / in <dotcms-video … /> and would swallow the content after it. Both carriers produce identical stored documents.

Block styling (e.g. text alignment) is set by an HTML comment on its own line immediately before the block it decorates, in Markdown and HTML alike: <!-- dotcms:attrs {"textAlign":"center"} -->.

A Markdown/HTML write fully replaces the stored document; when stored rich blocks are not carried over in the submitted value, the save still succeeds and an advisory warning listing the replaced blocks is returned in the response messages field — carry the blocks over as fences or elements to preserve them. An invalid payload degrades to an ordinary code block (or is dropped when it carries no text to keep), never an error.