Create Cascade Asset

Create a new asset in Cascade CMS.

The request body wraps a typed envelope under asset — one of 48 envelope keys (page, file, folder, symlink, textBlock, feedBlock, indexBlock, xmlBlock, xhtmlDataDefinitionBlock, twitterFeedBlock, reference, template, xsltFormat, scriptFormat, user, group, role, assetFactory, contentType, destination, editorConfiguration, metadataSet, pageConfigurationSet, publishSet, dataDefinition, sharedField, site, workflowDefinition, workflowEmail, wordPressConnector, googleAnalyticsConnector, fileSystemTransport, ftpTransport, databaseTransport, cloudTransport, and the *Container types). This matches the upstream Cascade REST API Asset schema exactly. Returns the new asset's ID on success.

Payload conventions (apply to every create call):

• Send ONLY the fields you actually need to set. Every optional field should be omitted unless you have a real value to provide — Cascade applies its own defaults server-side. Do not pad payloads with "reasonable defaults" like reviewOnSchedule: false or shouldBePublished: true when you do not need to override them.

• For every <thing>Id / <thing>Path pair (parentFolderId vs parentFolderPath, siteId vs siteName, contentTypeId vs contentTypePath, metadataSetId vs metadataSetPath, ...), prefer the id form when you know the id. Path is a valid fallback and Cascade resolves it server-side — don't round-trip through cascade_read just to look up an id.

• Text encoding: rich-text fields (xhtml, WYSIWYG structuredData text, xmlBlock xml) must be well-formed XML — named HTML entities like   and astral-plane Unicode (including emoji) crash the render. See resource cascade://text-encoding for the per-field-category rules.

Args:

• asset (object, required): Single-key envelope. Key is the camelCase type; value is the asset body. Common shapes (only required fields shown — add optionals only when you need to set them):

  • { page: { name, parentFolderId OR parentFolderPath, siteId OR siteName, contentTypeId OR contentTypePath, ... } }

  • { file: { name, parentFolderId OR parentFolderPath, siteId OR siteName, text? OR data?, ... } }

  • { folder: { name, parentFolderId OR parentFolderPath, siteId OR siteName, ... } }

  • { textBlock: { name, parentFolderId OR parentFolderPath, siteId OR siteName, text, ... } }

  • { xmlBlock: { name, parentFolderId OR parentFolderPath, siteId OR siteName, xml, ... } }

  • { symlink: { name, parentFolderId OR parentFolderPath, siteId OR siteName, linkURL, ... } } Admin-area types (assetFactory, contentType, transports, workflow*, *Container) use parentContainerId/Path instead of parentFolderId/Path.

Returns: Cascade OperationResult: { success: true, createdAssetId: "" } On failure: { success: false, message: "" }

Examples:

• Use when: "Create a page under /about" -> { asset: { page: { name: "team", parentFolderPath: "/about", siteName: "www", contentTypePath: "/standard-page" } } }

• Use when: "Upload a text file" -> { asset: { file: { name: "robots.txt", parentFolderPath: "/", siteName: "www", text: "User-agent: *" } } }

• Use when: "Create a text block" -> { asset: { textBlock: { name: "greeting", parentFolderPath: "/blocks", siteName: "www", text: "Hello" } } }

• Don't use when: The asset already exists — use cascade_edit.

• Don't use when: You want to duplicate an existing asset — use cascade_copy.

Error Handling:

• "Parent folder not found" when parentFolderId/parentFolderPath is invalid

• "Asset name collision" when an asset with the same name exists in the parent

• "Permission denied" when credentials lack create access on the parent

• "Invalid content type" when contentTypeId/contentTypePath doesn't resolve. Responses are JSON text; structuredContent is authoritative when the response fits. Oversized responses return bounded _cache metadata for cascade_read_response. For cascade_read, read_mode controls preview versus raw Cascade payload shape.