roam_create_outline
Add a structured outline to an existing page or block with customizable nesting levels. Organize supplementary content, meeting notes, or research under a specific topic for clear hierarchical structure.
Instructions
Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. To create a new page with an outline, use the roam_create_page tool instead. The outline parameter defines new blocks to be created. To nest content under an existing block, provide its UID or exact text in block_text_uid, and ensure the outline array contains only the child blocks with levels relative to that parent. Including the parent block's text in the outline array will create a duplicate block. Best for:
Adding supplementary structured content to existing pages
Creating temporary or working outlines (meeting notes, brainstorms)
Organizing thoughts or research under a specific topic
Breaking down subtopics or components of a larger concept Best for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider
roam_process_batch_actionsinstead. API Usage Note: This tool performs verification queries after creation. For large outlines (10+ items) or when rate limits are a concern, consider usingroam_process_batch_actionsinstead to minimize API calls. IMPORTANT: Before using this tool, ensure that you have loaded into context the 'Roam Markdown Cheatsheet' resource.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page_title_uid | No | Title or UID of the page (UID is preferred for accuracy). Leave blank to use the default daily page. | |
| block_text_uid | No | The text content or UID of the block to nest the outline under (UID is preferred for accuracy). If blank, content is nested directly under the page (or the default daily page if page_title_uid is also blank). | |
| outline | Yes | Array of outline items with block text and explicit nesting level. Must be a valid hierarchy: the first item must be level 1, and subsequent levels cannot increase by more than 1 at a time (e.g., a level 3 cannot follow a level 1). | |
| order | No | Insertion position for the first level-1 block relative to existing page/block children. Accepts "first", "last", or a non-negative integer (0-indexed). Default: "last". | |
| graph | No | Target graph key from ROAM_GRAPHS config. Defaults to ROAM_DEFAULT_GRAPH. Only needed in multi-graph mode. | |
| write_key | No | Write confirmation key. Required for write operations on non-default graphs when write_key is configured. |