[{"data":1,"prerenderedAt":634},["ShallowReactive",2],{"/api/concepts/blocks":3,"/api/concepts/blocks-surround":627},{"id":4,"title":5,"body":6,"description":618,"extension":619,"links":620,"meta":621,"navigation":622,"path":623,"seo":624,"stem":625,"__hash__":626},"docs/api/2.concepts/blocks.md","Blocks",{"type":7,"value":8,"toc":608},"minimark",[9,18,37,114,119,245,249,275,279,303,307,334,342,346,370,422,450,454,481,485,536,539,547,551,564,604],[10,11,12,13,17],"p",{},"Many objects store body content in ",[14,15,16],"strong",{},"blocks"," — structured trees attached to block properties (for example a page's main content or a daily note's notes field).",[10,19,20,21,29,30,32,33,36],{},"On ",[22,23,25],"a",{"href":24},"/api/reference",[26,27,28],"code",{},"GET /object",", block trees appear under ",[26,31,16],{},", keyed by ",[14,34,35],{},"property definition id",":",[38,39,44],"pre",{"className":40,"code":41,"language":42,"meta":43,"style":43},"language-json shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","{\n  \"blocks\": {\n    \"content\": [\n      /* array of root-level blocks */\n    ]\n  }\n}\n","json","",[26,45,46,55,72,89,96,102,108],{"__ignoreMap":43},[47,48,51],"span",{"class":49,"line":50},"line",1,[47,52,54],{"class":53},"sMK4o","{\n",[47,56,58,61,64,67,69],{"class":49,"line":57},2,[47,59,60],{"class":53},"  \"",[47,62,16],{"class":63},"spNyl",[47,65,66],{"class":53},"\"",[47,68,36],{"class":53},[47,70,71],{"class":53}," {\n",[47,73,75,78,82,84,86],{"class":49,"line":74},3,[47,76,77],{"class":53},"    \"",[47,79,81],{"class":80},"sBMFI","content",[47,83,66],{"class":53},[47,85,36],{"class":53},[47,87,88],{"class":53}," [\n",[47,90,92],{"class":49,"line":91},4,[47,93,95],{"class":94},"sHwdD","      /* array of root-level blocks */\n",[47,97,99],{"class":49,"line":98},5,[47,100,101],{"class":53},"    ]\n",[47,103,105],{"class":49,"line":104},6,[47,106,107],{"class":53},"  }\n",[47,109,111],{"class":49,"line":110},7,[47,112,113],{"class":53},"}\n",[115,116,118],"h2",{"id":117},"block-types","Block types",[120,121,122,137],"table",{},[123,124,125],"thead",{},[126,127,128,134],"tr",{},[129,130,131],"th",{},[26,132,133],{},"type",[129,135,136],{},"Role",[138,139,140,158,168,182,200,212,225,235],"tbody",{},[126,141,142,148],{},[143,144,145],"td",{},[26,146,147],{},"TextBlock",[143,149,150,151,155,156],{},"Paragraph or heading with inline ",[22,152,154],{"href":153},"/api/concepts/text-tokens","text tokens"," and optional nested ",[26,157,16],{},[126,159,160,165],{},[143,161,162],{},[26,163,164],{},"GroupBlock",[143,166,167],{},"Container for nested blocks (lists, toggles)",[126,169,170,175],{},[143,171,172],{},[26,173,174],{},"GridBlock",[143,176,177,178,181],{},"Multi-column layout (",[26,179,180],{},"columns"," is an array of block arrays)",[126,183,184,189],{},[143,185,186],{},[26,187,188],{},"CodeBlock",[143,190,191,192,195,196,199],{},"Fenced code (",[26,193,194],{},"lang",", ",[26,197,198],{},"text",")",[126,201,202,207],{},[143,203,204],{},[26,205,206],{},"MathBlock",[143,208,209,210,199],{},"Display math (LaTeX in ",[26,211,198],{},[126,213,214,219],{},[143,215,216],{},[26,217,218],{},"EntityBlock",[143,220,221,222,199],{},"Embedded Capacities object (",[26,223,224],{},"entityId",[126,226,227,232],{},[143,228,229],{},[26,230,231],{},"HorizontalLineBlock",[143,233,234],{},"Divider",[126,236,237,242],{},[143,238,239],{},[26,240,241],{},"unsupported",[143,243,244],{},"Placeholder when the type is not yet exposed",[115,246,248],{"id":247},"text-tokens","Text tokens",[10,250,251,252,254,255,258,259,261,262,195,265,195,268,195,271,274],{},"Each ",[26,253,147],{}," has a ",[26,256,257],{},"tokens"," array of ",[22,260,154],{"href":153}," (",[26,263,264],{},"TextToken",[26,266,267],{},"LinkToken",[26,269,270],{},"MathToken",[26,272,273],{},"CodeToken","). See that page for types, fields, and examples.",[115,276,278],{"id":277},"hierarchy-and-list-metadata","Hierarchy and list metadata",[10,280,281,283,284,287,288,291,292,195,295,298,299,302],{},[26,282,147],{}," includes ",[26,285,286],{},"hierarchy: { key, val }"," for outline level. Optional fields include ",[26,289,290],{},"list"," (bullet/numbered), ",[26,293,294],{},"todo",[26,296,297],{},"toggle",", and ",[26,300,301],{},"quote",".",[115,304,306],{"id":305},"writable-blocks","Writable blocks",[10,308,309,310,313,314,317,318,321,322,325,326,329,330,333],{},"When ",[14,311,312],{},"creating"," or ",[14,315,316],{},"appending"," blocks, you send ",[14,319,320],{},"writable"," block objects. You may omit ",[26,323,324],{},"id"," on new blocks — the server assigns ids. For ",[14,327,328],{},"patching"," a single block (",[26,331,332],{},"PATCH /blocks/block","), the existing block id is preserved.",[10,335,336,338,339,341],{},[26,337,218],{}," references use ",[26,340,224],{}," to link to another object by id.",[115,343,345],{"id":344},"append-position","Append position",[10,347,348,353,354,359,360,195,363,298,366,369],{},[22,349,350],{"href":24},[26,351,352],{},"POST /blocks/append"," and ",[22,355,356],{"href":24},[26,357,358],{},"POST /blocks/markdown/append"," accept optional ",[26,361,362],{},"position",[26,364,365],{},"parentBlockId",[26,367,368],{},"propertyId"," (defaults to the structure’s main content property when omitted).",[120,371,372,384],{},[123,373,374],{},[126,375,376,381],{},[129,377,378],{},[26,379,380],{},"position.type",[129,382,383],{},"Behavior",[138,385,386,396,406],{},[126,387,388,393],{},[143,389,390],{},[26,391,392],{},"end",[143,394,395],{},"End of the target list (default)",[126,397,398,403],{},[143,399,400],{},[26,401,402],{},"start",[143,404,405],{},"Beginning of the list",[126,407,408,413],{},[143,409,410],{},[26,411,412],{},"after_block",[143,414,415,416,419,420,199],{},"Immediately after ",[26,417,418],{},"after_block.id"," (do not set ",[26,421,365],{},[10,423,424,425,427,428,430,431,433,434,353,438,442,443,195,445,195,447,449],{},"For ",[26,426,392],{}," / ",[26,429,402],{},", omit ",[26,432,365],{}," to append at the property root, or set it to a parent block id to nest inside that block. Only ",[14,435,436],{},[26,437,147],{},[14,439,440],{},[26,441,164],{}," may be parents. You cannot append into ",[26,444,188],{},[26,446,218],{},[26,448,206],{},", and similar leaf types.",[115,451,453],{"id":452},"updating-a-single-block","Updating a single block",[10,455,456,460,461,464,465,468,469,195,471,298,473,475,476,313,478,480],{},[22,457,458],{"href":24},[26,459,332],{}," replaces one block’s content. The block ",[14,462,463],{},"id is unchanged"," and the request ",[26,466,467],{},"block.type"," must match the existing block. For ",[26,470,147],{},[26,472,164],{},[26,474,174],{},", omit nested ",[26,477,16],{},[26,479,180],{}," to keep existing children; include them to replace the full child list.",[115,482,484],{"id":483},"block-mutations","Block mutations",[120,486,487,497],{},[123,488,489],{},[126,490,491,494],{},[129,492,493],{},"Operation",[129,495,496],{},"Endpoint",[138,498,499,508,517,526],{},[126,500,501,504],{},[143,502,503],{},"Append blocks",[143,505,506],{},[26,507,352],{},[126,509,510,513],{},[143,511,512],{},"Append Markdown",[143,514,515],{},[26,516,358],{},[126,518,519,522],{},[143,520,521],{},"Update one block",[143,523,524],{},[26,525,332],{},[126,527,528,531],{},[143,529,530],{},"Delete blocks",[143,532,533],{},[26,534,535],{},"POST /blocks/delete",[10,537,538],{},"Deleting a block removes its entire subtree — do not list child ids separately.",[10,540,541,542,546],{},"For many write and read flows you can use ",[22,543,545],{"href":544},"/api/concepts/markdown","Markdown"," instead of building block JSON — especially helpful for AI-generated content.",[115,548,550],{"id":549},"daily-notes","Daily notes",[10,552,553,353,558,563],{},[22,554,555],{"href":24},[26,556,557],{},"POST /blocks/daily-note/append",[22,559,560],{"href":24},[26,561,562],{},"POST /blocks/markdown/daily-note"," append content to the daily note for a given day in the token’s space.",[565,566,567,575,592,598],"ul",{},[568,569,570,571,574],"li",{},"Requests are processed ",[14,572,573],{},"asynchronously"," — the endpoint returns when the job is queued, not when the note is fully saved.",[568,576,577,578,581,582,261,585,588,589,591],{},"Optional ",[26,579,580],{},"date"," selects the daily note day as an ISO 8601 timestamp at ",[14,583,584],{},"UTC midnight",[26,586,587],{},"…T00:00:00.000Z","). Omit ",[26,590,580],{}," to use today (UTC).",[568,593,577,594,597],{},[26,595,596],{},"noTimeStamp: true"," skips the automatic timestamp heading block when appending.",[568,599,600,601,603],{},"The blocks endpoints accept a full block tree; the Markdown endpoints accept a Markdown string (see ",[22,602,545],{"href":544},").",[605,606,607],"style",{},"html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html pre.shiki code .spNyl, html code.shiki .spNyl{--shiki-light:#9C3EDA;--shiki-default:#C792EA;--shiki-dark:#C792EA}html pre.shiki code .sBMFI, html code.shiki .sBMFI{--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B}html pre.shiki code .sHwdD, html code.shiki .sHwdD{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#676E95;--shiki-dark-font-style:italic}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":43,"searchDepth":50,"depth":57,"links":609},[610,611,612,613,614,615,616,617],{"id":117,"depth":57,"text":118},{"id":247,"depth":57,"text":248},{"id":277,"depth":57,"text":278},{"id":305,"depth":57,"text":306},{"id":344,"depth":57,"text":345},{"id":452,"depth":57,"text":453},{"id":483,"depth":57,"text":484},{"id":549,"depth":57,"text":550},"Block trees, inline tokens, and how block mutations work in the Capacities API.","md",null,{},true,"/api/concepts/blocks",{"title":5,"description":618},"api/2.concepts/blocks","rkbhyyASyC2d3bnIJh6Ckiq4CjKqNkdJ6AmzXGasgWU",[628,632],{"title":629,"path":630,"stem":631,"children":-1},"Versioning","/api/overview/versioning","api/1.overview/versioning",{"title":545,"path":544,"stem":633,"children":-1},"api/2.concepts/markdown",1781012286256]