Notion

Notion

Notion organizes content as pages (documents) and databases (structured tables). Pages contain blocks (paragraphs, headings, lists, toggles, etc.) as children. Databases have typed properties (title, text, number, select, date, etc.) and rows are pages with property values.

Data Model

• Pages are documents with properties and block children. Every database row is also a page.
• Databases define a schema via properties. Query with filters and sorts.
• Blocks are content units: paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item, to_do, toggle, code, image, etc.
• Users are workspace members (person or bot type).
• Comments are threaded discussions on pages or specific blocks.

Common Patterns

• Search finds pages and databases by title. Use filter to narrow to pages or databases only.
• Read page content: Render a page as human-readable Markdown. Fetch block children only when you need the raw block JSON.
• Write content with Markdown: New pages and appended blocks both accept a markdown_content parameter. Pass Markdown text and it's automatically converted to Notion blocks. Supports headings, lists, to-dos, code blocks, quotes, images, and inline formatting.
• Query database: Use filter objects with property-based conditions. Sorts accept property name + direction.
• Create page in database: Set parent to database_id and provide property values matching the database schema.
• Create page as child: Set parent to page_id and provide content via markdown_content or raw children blocks.
• Move a page: Move/reparent a page under a different page or database.
• IDs: UUIDv4 format. Dashes can be omitted. Use the full UUID with dashes when passing ids into parameters.

Gotchas

• Pagination: Paged listings return at most 100 items. Use start_cursor from the response to continue.
• Rich text: Text content is represented as arrays of rich_text objects with type, text.content, and annotations. When using markdown_content, this is handled automatically.
• Property values vary by type: Each property type (title, rich_text, number, select, date, etc.) has its own value format.
• Archived = deleted: Setting archived=true on a page or block is how you delete in Notion.
• Markdown vs raw blocks: Use markdown_content for natural content creation. Use raw children blocks only when you need precise control over block structure (e.g., toggles, callouts, synced blocks).