Core concepts
Understand MuseCanto data models, entity relationships, state lifecycles, and security boundaries.
MuseCanto structures content production into a modular, collaborative entity model. Understanding these core concepts ensures you make the most out of workspace teamwork, multi-platform distribution, and AI automation.
Entity Relationship Architecture
The diagram below illustrates the topology of core entities within MuseCanto:
Core Entities Breakdown
1. Workspace (Organization)
- Definition: The primary boundary for data isolation and access control.
- Function: Members, roles (Owner, Admin, Member), libraries, documents, and billing quotas all belong to a specific workspace. Solo creators operate within personal workspaces, while media teams share team workspaces.
- Developer Note: In API calls and MCP tooling, workspaces are indexed by their unique
organizationSlug.
2. Topic & Content Calendar
- Definition: The conceptual home for early ideas, creative briefs, and publishing schedules.
- Attributes: Title, creative hook, category tag, assignee, and target Planning Date.
- Important Distinction: A topic's planning date is purely an internal planning milestone—it never automatically triggers external publishing.
3. Knowledge Library & Document
- Library: Operates like an online book or structured folder with nested categories for research and series writing.
- Document: Three kinds of canvas:
- Article: collaborative rich text; can ship through the browser extension.
- Gallery: a set of images with a cover and a prompt; hero plus filmstrip; does not ship through the extension.
- X post: thread editor; publish now or on a schedule through the official API.
- Versioning: Major article edits keep version history.
4. X Draft & Thread
- Definition: An ordered collection of posts tailored for social media threads.
- Capabilities: Multi-post thread splitting, media uploads, and real-time character boundary verification.
- Workflow: Drafts live inside MuseCanto until explicitly submitted for immediate or scheduled delivery.
5. Publish Job & Content Snapshot
- Content Snapshot: When initiating distribution, MuseCanto creates an immutable snapshot of the document at that exact revision. Editing the document afterward does not affect active publishing runs.
- Publish Job: The execution unit that orchestrates distribution across target platforms, tracking leases, state changes, and callback logs.
State Lifecycles: From Draft to Published
In multi-platform distribution, preparing a draft is fundamentally different from a live public post:
| Status Badge | Meaning | Typical Platform Behavior |
|---|---|---|
draft | Content is being drafted in the editor | Unsent document or X post in draft queue |
prepared | Browser extension has filled content into the destination editor | Zhihu / WeChat / Reddit: Body is pasted, awaiting human final review |
scheduled | Cloud cron task is queued and waiting for trigger time | X Thread: Handled by Cloudflare Worker Cron high-availability workers |
published | Content has been publicly sent to destination | Post confirmed with public permalink |
failed | The execution encountered an error | Expired platform session, network failure, or platform spam shield |
Draft Filling vs Public Publishing
Except for direct X thread publishing, extension distribution to platforms like WeChat and Zhihu defaults to safe draft filling. This gives creators final approval to review platform-specific previews, cover images, and compliance checks before publishing live.
Identifiers (IDs) and Access Standards
When building scripts or configuring MCP agents:
- Workspace Identifier: Always supply the
organizationSlug(e.g.,my-team). - Resource IDs: Documents, libraries, and topics use unique UUIDs (e.g.,
doc_01j4k8...). Do not pass web URLs in place of resource IDs.