Notion API SOPs

Appearance

Object Types Reference ​

Fresh Schema definitions for Notion API objects.

Object Hierarchy ​

Page Object ​

javascript
{
  "object": "page",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "created_time": "2025-01-15T10:00:00.000Z",
  "last_edited_time": "2025-01-15T12:00:00.000Z",
  "created_by": { "object": "user", "id": "xxx" },
  "last_edited_by": { "object": "user", "id": "xxx" },
  "cover": null,
  "icon": { "type": "emoji", "emoji": "📄" },
  "parent": {
    "type": "database_id",
    "database_id": "xxx"
  },
  "archived": false,
  "in_trash": false,
  "properties": { /* property values */ },
  "url": "https://www.notion.so/Page-Title-xxx"
}

Database Object ​

javascript
{
  "object": "database",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "created_time": "2025-01-15T10:00:00.000Z",
  "last_edited_time": "2025-01-15T12:00:00.000Z",
  "title": [/* rich text array */],
  "description": [/* rich text array */],
  "icon": null,
  "cover": null,
  "properties": { /* property schema */ },
  "parent": {
    "type": "page_id",
    "page_id": "xxx"
  },
  "url": "https://www.notion.so/xxx",
  "archived": false,
  "in_trash": false,
  "is_inline": false
}

Property Types ​

Property Schema (Database Definition) ​

Property Schema Examples ​

javascript
{
  "Name": {
    "id": "title",
    "name": "Name",
    "type": "title",
    "title": {}
  }
}
javascript
{
  "Description": {
    "id": "xxx",
    "name": "Description",
    "type": "rich_text",
    "rich_text": {}
  }
}
javascript
{
  "Price": {
    "id": "xxx",
    "name": "Price",
    "type": "number",
    "number": {
      "format": "dollar"
    }
  }
}

// Formats: number, number_with_commas, percent,
// dollar, canadian_dollar, euro, pound, yen,
// ruble, rupee, won, yuan, real, lira, and more
javascript
{
  "Status": {
    "id": "xxx",
    "name": "Status",
    "type": "select",
    "select": {
      "options": [
        { "id": "xxx", "name": "To Do", "color": "gray" },
        { "id": "xxx", "name": "Done", "color": "green" }
      ]
    }
  }
}
javascript
{
  "Tags": {
    "id": "xxx",
    "name": "Tags",
    "type": "multi_select",
    "multi_select": {
      "options": [
        { "id": "xxx", "name": "Bug", "color": "red" },
        { "id": "xxx", "name": "Feature", "color": "blue" }
      ]
    }
  }
}
javascript
{
  "Due Date": {
    "id": "xxx",
    "name": "Due Date",
    "type": "date",
    "date": {}
  }
}
javascript
{
  "Archived": {
    "id": "xxx",
    "name": "Archived",
    "type": "checkbox",
    "checkbox": {}
  }
}
javascript
{
  "Assignee": {
    "id": "xxx",
    "name": "Assignee",
    "type": "people",
    "people": {}
  }
}
javascript
{
  "Website": {
    "id": "xxx",
    "name": "Website",
    "type": "url",
    "url": {}
  }
}
javascript
{
  "Projects": {
    "id": "xxx",
    "name": "Projects",
    "type": "relation",
    "relation": {
      "database_id": "xxx",
      "type": "dual_property",
      "dual_property": {
        "synced_property_name": "Tasks",
        "synced_property_id": "xxx"
      }
    }
  }
}
javascript
{
  "Total": {
    "id": "xxx",
    "name": "Total",
    "type": "rollup",
    "rollup": {
      "relation_property_name": "Items",
      "relation_property_id": "xxx",
      "rollup_property_name": "Price",
      "rollup_property_id": "xxx",
      "function": "sum"
    }
  }
}

// Functions: count, count_values, empty, not_empty,
// unique, show_unique, percent_empty, percent_not_empty,
// sum, average, median, min, max, range, earliest_date,
// latest_date, date_range, checked, unchecked,
// percent_checked, percent_unchecked, show_original
javascript
{
  "Calculated": {
    "id": "xxx",
    "name": "Calculated",
    "type": "formula",
    "formula": {
      "expression": "prop(\"Price\") * prop(\"Quantity\")"
    }
  }
}

Property Values (Page Properties) ​

javascript
{
  "Name": {
    "id": "title",
    "type": "title",
    "title": [
      {
        "type": "text",
        "text": { "content": "Page Title", "link": null },
        "plain_text": "Page Title",
        "annotations": { /* ... */ },
        "href": null
      }
    ]
  }
}
javascript
{
  "Description": {
    "id": "xxx",
    "type": "rich_text",
    "rich_text": [
      {
        "type": "text",
        "text": { "content": "Some text" },
        "plain_text": "Some text"
      }
    ]
  }
}
javascript
{
  "Price": {
    "id": "xxx",
    "type": "number",
    "number": 99.99
  }
}
javascript
{
  "Status": {
    "id": "xxx",
    "type": "select",
    "select": {
      "id": "xxx",
      "name": "Done",
      "color": "green"
    }
  }
}
javascript
{
  "Tags": {
    "id": "xxx",
    "type": "multi_select",
    "multi_select": [
      { "id": "xxx", "name": "Bug", "color": "red" },
      { "id": "xxx", "name": "Feature", "color": "blue" }
    ]
  }
}
javascript
{
  "Due Date": {
    "id": "xxx",
    "type": "date",
    "date": {
      "start": "2025-01-15",
      "end": "2025-01-20",
      "time_zone": null
    }
  }
}
javascript
{
  "Completed": {
    "id": "xxx",
    "type": "checkbox",
    "checkbox": true
  }
}
javascript
{
  "Assignee": {
    "id": "xxx",
    "type": "people",
    "people": [
      {
        "object": "user",
        "id": "xxx",
        "name": "John Doe",
        "avatar_url": "https://...",
        "type": "person",
        "person": { "email": "john@example.com" }
      }
    ]
  }
}
javascript
{
  "Website": {
    "id": "xxx",
    "type": "url",
    "url": "https://example.com"
  }
}
javascript
{
  "Projects": {
    "id": "xxx",
    "type": "relation",
    "relation": [
      { "id": "page-id-1" },
      { "id": "page-id-2" }
    ],
    "has_more": false
  }
}

Block Types ​

Common Block Structure ​

javascript
{
  "object": "block",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "parent": {
    "type": "page_id",
    "page_id": "xxx"
  },
  "created_time": "2025-01-15T10:00:00.000Z",
  "last_edited_time": "2025-01-15T12:00:00.000Z",
  "created_by": { "object": "user", "id": "xxx" },
  "last_edited_by": { "object": "user", "id": "xxx" },
  "has_children": false,
  "archived": false,
  "in_trash": false,
  "type": "paragraph",
  "paragraph": {
    "rich_text": [/* ... */],
    "color": "default"
  }
}

Block Type Examples ​

javascript
{
  "type": "paragraph",
  "paragraph": {
    "rich_text": [{ "text": { "content": "Text" } }],
    "color": "default"
  }
}
javascript
{
  "type": "heading_1",
  "heading_1": {
    "rich_text": [{ "text": { "content": "H1" } }],
    "is_toggleable": false,
    "color": "default"
  }
}
// Also: heading_2, heading_3
javascript
{
  "type": "bulleted_list_item",
  "bulleted_list_item": {
    "rich_text": [{ "text": { "content": "Item" } }],
    "color": "default"
  }
}

{
  "type": "numbered_list_item",
  "numbered_list_item": {
    "rich_text": [{ "text": { "content": "Item" } }],
    "color": "default"
  }
}

{
  "type": "to_do",
  "to_do": {
    "rich_text": [{ "text": { "content": "Task" } }],
    "checked": false,
    "color": "default"
  }
}
javascript
{
  "type": "code",
  "code": {
    "rich_text": [{ "text": { "content": "code" } }],
    "caption": [],
    "language": "javascript"
  }
}
javascript
{
  "type": "quote",
  "quote": {
    "rich_text": [{ "text": { "content": "Quote" } }],
    "color": "default"
  }
}
javascript
{
  "type": "callout",
  "callout": {
    "rich_text": [{ "text": { "content": "Note" } }],
    "icon": { "type": "emoji", "emoji": "💡" },
    "color": "blue_background"
  }
}
javascript
{
  "type": "toggle",
  "toggle": {
    "rich_text": [{ "text": { "content": "Toggle" } }],
    "color": "default"
  }
}
javascript
{
  "type": "divider",
  "divider": {}
}
javascript
{
  "type": "image",
  "image": {
    "type": "external",
    "external": {
      "url": "https://example.com/image.png"
    },
    "caption": []
  }
}
javascript
{
  "type": "table",
  "table": {
    "table_width": 3,
    "has_column_header": true,
    "has_row_header": false
  }
}
// Children must be table_row blocks
javascript
{
  "type": "bookmark",
  "bookmark": {
    "url": "https://example.com",
    "caption": []
  }
}

Rich Text Object ​

javascript
{
  "type": "text",
  "text": {
    "content": "Hello World",
    "link": { "url": "https://example.com" }  // optional
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "Hello World",
  "href": "https://example.com"  // null if no link
}

Available Colors ​

  • Text colors: default, gray, brown, orange, yellow, green, blue, purple, pink, red
  • Background colors: gray_background, brown_background, orange_background, yellow_background, green_background, blue_background, purple_background, pink_background, red_background

User Object ​

javascript
{
  "object": "user",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "person",  // or "bot"
  "name": "John Doe",
  "avatar_url": "https://...",
  "person": {
    "email": "john@example.com"
  }
}

Parent Objects ​

javascript
// Database parent
{ "type": "database_id", "database_id": "xxx" }

// Page parent
{ "type": "page_id", "page_id": "xxx" }

// Workspace parent
{ "type": "workspace", "workspace": true }

// Block parent
{ "type": "block_id", "block_id": "xxx" }

Icon Objects ​

javascript
// Emoji icon
{ "type": "emoji", "emoji": "📄" }

// External image
{
  "type": "external",
  "external": { "url": "https://example.com/icon.png" }
}

// Notion-hosted file
{
  "type": "file",
  "file": {
    "url": "https://prod-files-secure...",
    "expiry_time": "2025-01-15T12:00:00.000Z"
  }
}

Cover Objects ​

javascript
// External image
{
  "type": "external",
  "external": { "url": "https://example.com/cover.jpg" }
}

// Notion-hosted file
{
  "type": "file",
  "file": {
    "url": "https://prod-files-secure...",
    "expiry_time": "2025-01-15T12:00:00.000Z"
  }
}

See Also ​

Built with VitePress | Powered by Claude AI

© 2025 Notion API Documentation