admin/openclaw-workspace

Fork 0

Files

OpenClaw Agent 5deb387aa6 Fresh start - excluded large ROM JSON files

2026-04-11 09:45:12 -05:00

7.9 KiB

Raw Permalink Blame History

Notion Routing Reference

App name: notion Base URL proxied: api.notion.com

Required Headers

All Notion API requests require:

Notion-Version: 2025-09-03

API Path Pattern

/notion/v1/{endpoint}

Key Concept: Databases vs Data Sources

In API version 2025-09-03, databases and data sources are separate concepts:

Concept	Description	Use For
Database	Container that can hold multiple data sources	Creating databases, getting data_source IDs
Data Source	Schema and data within a database	Querying, updating schema, updating properties

Most existing databases have one data source. Use GET /databases/{id} to get the data_source_id, then use /data_sources/ endpoints for all operations.

Common Endpoints

Search

Search for pages:

POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "query": "meeting notes",
  "filter": {"property": "object", "value": "page"}
}

Search for data sources:

POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "filter": {"property": "object", "value": "data_source"}
}

With pagination:

POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "page_size": 10,
  "start_cursor": "CURSOR_FROM_PREVIOUS_RESPONSE"
}

Data Sources

Use data source endpoints for querying, getting schema, and updates.

Get Data Source

GET /notion/v1/data_sources/{dataSourceId}
Notion-Version: 2025-09-03

Returns full schema with properties field.

Query Data Source

POST /notion/v1/data_sources/{dataSourceId}/query
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "filter": {
    "property": "Status",
    "select": {"equals": "Active"}
  },
  "sorts": [
    {"property": "Created", "direction": "descending"}
  ],
  "page_size": 100
}

Update Data Source (title, schema, properties)

PATCH /notion/v1/data_sources/{dataSourceId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "title": [{"type": "text", "text": {"content": "Updated Title"}}],
  "properties": {
    "NewColumn": {"rich_text": {}}
  }
}

Databases

Database endpoints are only needed for creating databases and discovering data source IDs.

Get Database (to find data_source_id)

GET /notion/v1/databases/{databaseId}
Notion-Version: 2025-09-03

Response includes data_sources array:

{
  "id": "database-id",
  "object": "database",
  "data_sources": [{"id": "data-source-id", "name": "Database Name"}]
}

Note: This endpoint returns properties: null. Use GET /data_sources/{id} to get the schema.

Create Database

POST /notion/v1/databases
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"type": "page_id", "page_id": "PARENT_PAGE_ID"},
  "title": [{"type": "text", "text": {"content": "New Database"}}],
  "properties": {
    "Name": {"title": {}},
    "Status": {"select": {"options": [{"name": "Active"}, {"name": "Done"}]}}
  }
}

Important: Cannot create databases via /data_sources endpoint.

Pages

Get Page

GET /notion/v1/pages/{pageId}
Notion-Version: 2025-09-03

Create Page in Data Source

Use data_source_id (not database_id) as parent:

POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"data_source_id": "DATA_SOURCE_ID"},
  "properties": {
    "Name": {"title": [{"text": {"content": "New Page"}}]},
    "Status": {"select": {"name": "Active"}}
  }
}

Create Child Page (under another page)

POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"page_id": "PARENT_PAGE_ID"},
  "properties": {
    "title": {"title": [{"text": {"content": "Child Page"}}]}
  }
}

Update Page Properties

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "properties": {
    "Status": {"select": {"name": "Done"}}
  }
}

Archive Page

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "archived": true
}

Blocks

Get Block

GET /notion/v1/blocks/{blockId}
Notion-Version: 2025-09-03

Get Block Children

GET /notion/v1/blocks/{blockId}/children
Notion-Version: 2025-09-03

Append Block Children

PATCH /notion/v1/blocks/{blockId}/children
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{"type": "text", "text": {"content": "New paragraph"}}]
      }
    },
    {
      "object": "block",
      "type": "heading_2",
      "heading_2": {
        "rich_text": [{"type": "text", "text": {"content": "Heading"}}]
      }
    }
  ]
}

Update Block

PATCH /notion/v1/blocks/{blockId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "paragraph": {
    "rich_text": [{"text": {"content": "Updated text"}}]
  }
}

Delete Block

DELETE /notion/v1/blocks/{blockId}
Notion-Version: 2025-09-03

Users

List Users

GET /notion/v1/users
Notion-Version: 2025-09-03

Get User by ID

GET /notion/v1/users/{userId}
Notion-Version: 2025-09-03

Get Current User (Bot)

GET /notion/v1/users/me
Notion-Version: 2025-09-03

Filter Operators

equals, does_not_equal
contains, does_not_contain
starts_with, ends_with
is_empty, is_not_empty
greater_than, less_than, greater_than_or_equal_to, less_than_or_equal_to

Block Types

Common block types for appending:

paragraph - Text paragraph
heading_1, heading_2, heading_3 - Headings
bulleted_list_item, numbered_list_item - List items
to_do - Checkbox item
code - Code block
quote - Quote block
divider - Horizontal divider

Migration from Older API Versions

Old (2022-06-28)	New (2025-09-03)
`POST /databases/{id}/query`	`POST /data_sources/{id}/query`
`GET /databases/{id}` for schema	`GET /data_sources/{id}` for schema
`PATCH /databases/{id}` for schema	`PATCH /data_sources/{id}` for schema
Parent: `{"database_id": "..."}`	Parent: `{"data_source_id": "..."}`
Search filter: `"database"`	Search filter: `"data_source"`

Notes

Use GET /databases/{id} to discover data_source_id, then use /data_sources/ for all operations
Creating databases still requires POST /databases endpoint
Parent objects for create database require type field: {"type": "page_id", "page_id": "..."}
All IDs are UUIDs (with or without hyphens)
Delete blocks returns the block with archived: true

7.9 KiB Raw Permalink Blame History