create_workspace
Create a new workspace in the caller's org. Works for both user and agent callers; agent-created workspaces attribute to the agent and enroll the agent's owning user as a co-owner so the human sees it in their dashboard. The new workspace is seeded with one primary surface matching mode: doc → a Notes surface (for prose), table → a Sheet surface (for records), html → a Mockup surface (sandboxed HTML preview). Decide the surface before you create: prose (briefs, notes, summaries, drafts) → doc; records with shared columns (tasks, leads, rows) → table; a deliverable that IS html (a page, mockup, dashboard, or visual meant to be seen or shared) → html, then write it with update_html — never to a local file, which the human can't see. If you omit mode, pass initial_markdown to signal a doc; with neither mode nor initial_markdown, an agent caller gets a guided error asking it to choose doc or table (so you never silently land on the wrong surface). An explicit mode is always honored. html is opt-in — never inferred for ambiguous content — so pass it explicitly when the deliverable is html (a mockup, page, or dashboard the user asked for), and only then. Add more surfaces of any kind later via create_surface. Agent-created workspaces default to org-visibility so sibling agents in the same org aren't 403'd. For prose content (briefs, summaries, changelogs) pass initial_markdown to seed the doc body in one call; the markdown is converted server-side, no need to hand-build ProseMirror JSON.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Kind of the seeded primary surface — choose by what you're about to write. `doc` mints a Notes surface: use it for PROSE (briefs, notes, summaries, drafts, status reports). `table` mints a Sheet surface: use it for RECORDS (tasks, leads, rows, anything with shared columns). `html` mints a Mockup surface (sandboxed HTML preview): opt in by passing it explicitly whenever the deliverable IS html — a landing-page mockup, a dashboard, a design preview, any page meant to be looked at — and write it with `update_html`; it is never inferred for ambiguous content. Pass this explicitly: when omitted, `initial_markdown` resolves the surface to a `doc`; with neither, an agent caller gets a guided error asking it to choose (no silent default to a Sheet, which would be the wrong surface if you meant prose). Add more surfaces of any kind via `create_surface` later. | |
| name | Yes | The workspace name. Required. Used to derive a slug if you don't pass one. | |
| slug | No | Optional URL-friendly slug (lowercase, kebab-case, 3-64 chars). Auto-derived from `name` if omitted; if the derived slug collides within your org, a -N suffix is appended. | |
| initial_markdown | No | Optional Markdown body to seed the workspace's doc surface on create. CommonMark + GFM (tables, task lists, strikethrough). When provided AND mode is omitted, mode defaults to 'doc'. Skips the empty default-column scaffolding too. Ignored when mode='html' (no markdown equivalent for HTML surfaces — use `update_html` after create). Use this for any prose-shaped output (briefs, summaries, status updates, changelog entries) instead of create + update_doc with hand-built JSON. |