Read Cascade Asset

Read an asset from Cascade CMS by identifier.

Default preview mode returns a compact browse-oriented asset_handle, asset identity, raw_hash, index_version, fact/reference counts, node counts, root nodelet outline, and raw_resource_uri. Preview is not audit-complete; use cascade_asset_list_facts, cascade_asset_search_values, cascade_asset_search_keys, cascade_asset_get_value, cascade_asset_list_scalar_artifacts, cascade_asset_list_references, cascade_asset_list_nodelets, and cascade_asset_get_nodelet with the returned asset_handle for follow-up inspection. Use read_mode: "raw" only when the full REST payload is required.

Args:

• identifier (object, required): The asset to read

  • id (string, optional): Cascade internal asset ID (e.g., "d3631e59ac1e..."). Takes priority over path when both are provided.

  • path (object, optional): Site-qualified path

    • path (string, required): Asset path within the site, starting from root (e.g., "/about/team")

    • siteId OR siteName (string): Which site the path belongs to

  • type (string, required): Entity type — one of the 56 EntityTypeString values (page, file, folder, block, template, etc.)

  • recycled (boolean, optional): Read from recycle bin.

• read_mode (string, optional): 'preview' (default, compact handle-based output) or 'raw' (full REST payload; expensive for structured assets). Returns: Preview mode: { asset_handle, asset_type, asset_identity, raw_resource_uri, raw_hash, index_version, audit_complete: false, total_fact_count, reference_count, node_count, max_depth, root_outline, omitted_fields, warnings, next_actions } Raw mode: { success: true, asset: { : { ...type-specific representation } } } On failure: { success: false, message: "Asset not found" }

Examples:

• Use when: "Read the homepage" -> { identifier: { type: "page", path: { path: "/", siteName: "www" } } }

• Use when: "Get file by ID" -> { identifier: { type: "file", id: "abc123..." } }

• Use when: "Load folder config" -> { identifier: { type: "folder", path: { path: "/about", siteName: "www" } } }

• Don't use when: You want to modify — use cascade_edit instead.

• Don't use when: You want to check access rights — use cascade_read_access_rights.

Error Handling:

• "Asset not found" when the identifier doesn't resolve

• "Permission denied" when credentials lack read access

• "Site not found" when siteName/siteId is invalid. 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.