# Notion Quick Reference

## Property Types

**title** — Page name (exactly one per database page)

```json
{ "title": [{ "text": { "content": "Page Title" } }] }
```

**rich_text** — Formatted text

```json
{ "rich_text": [{ "text": { "content": "Some text" } }] }
```

**select** — Single option: `{"select": {"name": "Option"}}`

**multi_select** — Multiple options: `{"multi_select": [{"name": "Tag1"}, {"name": "Tag2"}]}`

**status** — Built-in status: `{"status": {"name": "In progress"}}`

**date** — Date or range: `{"date": {"start": "2024-01-15"}}` or `{"date": {"start": "2024-01-15", "end": "2024-01-20"}}`

**checkbox** — Boolean: `{"checkbox": true}`

**number** — Numeric: `{"number": 42}`

**url** — Link: `{"url": "https://example.com"}`

**people** — User references: `{"people": [{"id": "user-uuid"}]}`

**relation** — Links to other pages: `{"relation": [{"id": "page-uuid"}]}`

## Common Filters

**Text contains**: `{"property": "Name", "title": {"contains": "keyword"}}`

**Select equals**: `{"property": "Status", "select": {"equals": "Active"}}`

**Status equals**: `{"property": "Status", "status": {"equals": "Done"}}`

**Multi-select contains**: `{"property": "Tags", "multi_select": {"contains": "urgent"}}`

**Checkbox**: `{"property": "Done", "checkbox": {"equals": true}}`

**Date filters**:

- `{"property": "Due", "date": {"before": "2024-01-01"}}`
- `{"property": "Due", "date": {"after": "2024-01-01"}}`
- `{"property": "Due", "date": {"this_week": {}}}`
- `{"property": "Due", "date": {"next_week": {}}}`

**Compound (AND/OR)**:

```json
{
  "and": [
    { "property": "Status", "status": { "does_not_equal": "Done" } },
    { "property": "Due", "date": { "before": "2024-02-01" } }
  ]
}
```

## Sorts

```json
{"sorts": [{"property": "Due", "direction": "ascending"}]}
{"sorts": [{"timestamp": "last_edited_time", "direction": "descending"}]}
```

## Common Blocks

**paragraph**

```json
{
  "type": "paragraph",
  "paragraph": {
    "rich_text": [{ "type": "text", "text": { "content": "Text here" } }]
  }
}
```

**heading_1 / heading_2 / heading_3**

```json
{
  "type": "heading_1",
  "heading_1": {
    "rich_text": [{ "type": "text", "text": { "content": "Heading" } }]
  }
}
```

**bulleted_list_item**

```json
{
  "type": "bulleted_list_item",
  "bulleted_list_item": {
    "rich_text": [{ "type": "text", "text": { "content": "Item" } }]
  }
}
```

**numbered_list_item**

```json
{
  "type": "numbered_list_item",
  "numbered_list_item": {
    "rich_text": [{ "type": "text", "text": { "content": "Step" } }]
  }
}
```

**to_do**

```json
{
  "type": "to_do",
  "to_do": {
    "rich_text": [{ "type": "text", "text": { "content": "Task" } }],
    "checked": false
  }
}
```

**callout**

```json
{
  "type": "callout",
  "callout": {
    "rich_text": [{ "type": "text", "text": { "content": "Note" } }],
    "icon": { "type": "emoji", "emoji": "💡" }
  }
}
```

**code**

```json
{
  "type": "code",
  "code": {
    "rich_text": [{ "type": "text", "text": { "content": "const x = 1;" } }],
    "language": "javascript"
  }
}
```

**divider**: `{"type": "divider", "divider": {}}`

**quote**

```json
{
  "type": "quote",
  "quote": {
    "rich_text": [{ "type": "text", "text": { "content": "Quote text" } }]
  }
}
```

**toggle** — Collapsible content with children

```json
{
  "type": "toggle",
  "toggle": {
    "rich_text": [{ "type": "text", "text": { "content": "Click to expand" } }],
    "children": [
      {
        "type": "paragraph",
        "paragraph": {
          "rich_text": [
            { "type": "text", "text": { "content": "Hidden content" } }
          ]
        }
      }
    ]
  }
}
```

**table** — Static table with rows (NOT a database - no filtering, sorting, or properties)

```json
{
  "type": "table",
  "table": {
    "table_width": 3,
    "has_column_header": true,
    "has_row_header": false,
    "children": [
      {
        "type": "table_row",
        "table_row": {
          "cells": [
            [{ "type": "text", "text": { "content": "Header 1" } }],
            [{ "type": "text", "text": { "content": "Header 2" } }],
            [{ "type": "text", "text": { "content": "Header 3" } }]
          ]
        }
      },
      {
        "type": "table_row",
        "table_row": {
          "cells": [
            [{ "type": "text", "text": { "content": "Cell 1" } }],
            [{ "type": "text", "text": { "content": "Cell 2" } }],
            [{ "type": "text", "text": { "content": "Cell 3" } }]
          ]
        }
      }
    ]
  }
}
```

## Nested Blocks

Some blocks support children (toggle, callout, quote, bulleted_list_item, numbered_list_item). Add a `children` array:

```json
{
  "type": "bulleted_list_item",
  "bulleted_list_item": {
    "rich_text": [{ "type": "text", "text": { "content": "Parent item" } }],
    "children": [
      {
        "type": "bulleted_list_item",
        "bulleted_list_item": {
          "rich_text": [
            { "type": "text", "text": { "content": "Nested item" } }
          ]
        }
      }
    ]
  }
}
```

## Rich Text Formatting

```json
{"type": "text", "text": {"content": "Bold text"}, "annotations": {"bold": true}}
{"type": "text", "text": {"content": "Link", "link": {"url": "https://..."}}}
```

Colors: default, gray, brown, orange, yellow, green, blue, purple, pink, red. Add `_background` for highlights.

## Table Block vs Inline Database

**These are NOT the same:**

| Concept             | What it is                        | When to use                                                    |
| ------------------- | --------------------------------- | -------------------------------------------------------------- |
| **Table block**     | Static grid, no database features | Simple data display, no filtering/sorting needed               |
| **Inline database** | Full database embedded in page    | Needs properties, views, filtering, or will have entries added |

When users say "inline database", "embedded database", or "database in the page", use `parentType: "inline_database"` — NOT a table block.

## Inline Databases

Create a database inside a page using ``./skills/sauna//scripts/notion.workspace.write.js`` with `parentType: "inline_database"`.

**Important:** Inline databases cannot be added as blocks during page creation. Create the page first, then call the script with `parentType: inline_database` and the page ID.

**Always use the script.** It sets `is_inline: true` which embeds the database in the page content. Without this flag, you get a full-page database that's linked but not embedded—this is a common mistake when writing custom API code.

**Properties JSON format:**

```json
{
  "title": "My Database",
  "icon": "📊",
  "schema": {
    "Status": { "type": "select", "options": ["To Do", "In Progress", "Done"] },
    "Priority": { "type": "select", "options": ["Low", "Medium", "High"] },
    "Due Date": { "type": "date" },
    "Notes": { "type": "text" },
    "Count": { "type": "number" },
    "Completed": { "type": "checkbox" }
  }
}
```

**Supported column types:** `text`, `number`, `select`, `multi_select`, `status`, `date`, `checkbox`, `url`, `email`, `phone_number`

A "Name" title column is always created automatically.