Many objects store body content in blocks — structured trees attached to block properties (for example a page's main content or a daily note's notes field).

On GET /object, block trees appear under blocks, keyed by property definition id:

{
  "blocks": {
    "content": [
      /* array of root-level blocks */
    ]
  }
}

Block types

Text tokens

Each TextBlock has a tokens array of text tokens (TextToken, LinkToken, MathToken, CodeToken). See that page for types, fields, and examples.

Hierarchy and list metadata

TextBlock includes hierarchy: { key, val } for outline level. Optional fields include list (bullet/numbered), todo, toggle, and quote.

Writable blocks

When creating or appending blocks, you send writable block objects. You may omit id on new blocks — the server assigns ids. For patching a single block (PATCH /blocks/block), the existing block id is preserved.

EntityBlock references use entityId to link to another object by id.

Append position

POST /blocks/append and POST /blocks/markdown/append accept optional position, parentBlockId, and propertyId (defaults to the structure’s main content property when omitted).

For end / start, omit parentBlockId to append at the property root, or set it to a parent block id to nest inside that block. Only TextBlock and GroupBlock may be parents. You cannot append into CodeBlock, EntityBlock, MathBlock, and similar leaf types.

Updating a single block

PATCH /blocks/block replaces one block’s content. The block id is unchanged and the request block.type must match the existing block. For TextBlock, GroupBlock, and GridBlock, omit nested blocks or columns to keep existing children; include them to replace the full child list.

Block mutations

Deleting a block removes its entire subtree — do not list child ids separately.

For many write and read flows you can use Markdown instead of building block JSON — especially helpful for AI-generated content.

Daily notes

POST /blocks/daily-note/append and POST /blocks/markdown/daily-note append content to the daily note for a given day in the token’s space.

• Requests are processed asynchronously — the endpoint returns when the job is queued, not when the note is fully saved.
• Optional date selects the daily note day as an ISO 8601 timestamp at UTC midnight (…T00:00:00.000Z). Omit date to use today (UTC).
• Optional noTimeStamp: true skips the automatic timestamp heading block when appending.
• The blocks endpoints accept a full block tree; the Markdown endpoints accept a Markdown string (see Markdown).