Fresh start - excluded large ROM JSON files
This commit is contained in:
OpenClaw Agent
345
skills/api-gateway/references/notion.md
Normal file
345
skills/api-gateway/references/notion.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# 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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
POST /notion/v1/search
|
||||
Content-Type: application/json
|
||||
Notion-Version: 2025-09-03
|
||||
|
||||
{
|
||||
"filter": {"property": "object", "value": "data_source"}
|
||||
}
|
||||
```
|
||||
|
||||
With pagination:
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
GET /notion/v1/data_sources/{dataSourceId}
|
||||
Notion-Version: 2025-09-03
|
||||
```
|
||||
|
||||
Returns full schema with `properties` field.
|
||||
|
||||
#### Query Data Source
|
||||
```bash
|
||||
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)
|
||||
```bash
|
||||
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)
|
||||
```bash
|
||||
GET /notion/v1/databases/{databaseId}
|
||||
Notion-Version: 2025-09-03
|
||||
```
|
||||
|
||||
Response includes `data_sources` array:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
GET /notion/v1/pages/{pageId}
|
||||
Notion-Version: 2025-09-03
|
||||
```
|
||||
|
||||
#### Create Page in Data Source
|
||||
Use `data_source_id` (not `database_id`) as parent:
|
||||
```bash
|
||||
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)
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
PATCH /notion/v1/pages/{pageId}
|
||||
Content-Type: application/json
|
||||
Notion-Version: 2025-09-03
|
||||
|
||||
{
|
||||
"properties": {
|
||||
"Status": {"select": {"name": "Done"}}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Archive Page
|
||||
```bash
|
||||
PATCH /notion/v1/pages/{pageId}
|
||||
Content-Type: application/json
|
||||
Notion-Version: 2025-09-03
|
||||
|
||||
{
|
||||
"archived": true
|
||||
}
|
||||
```
|
||||
|
||||
### Blocks
|
||||
|
||||
#### Get Block
|
||||
```bash
|
||||
GET /notion/v1/blocks/{blockId}
|
||||
Notion-Version: 2025-09-03
|
||||
```
|
||||
|
||||
#### Get Block Children
|
||||
```bash
|
||||
GET /notion/v1/blocks/{blockId}/children
|
||||
Notion-Version: 2025-09-03
|
||||
```
|
||||
|
||||
#### Append Block Children
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
PATCH /notion/v1/blocks/{blockId}
|
||||
Content-Type: application/json
|
||||
Notion-Version: 2025-09-03
|
||||
|
||||
{
|
||||
"paragraph": {
|
||||
"rich_text": [{"text": {"content": "Updated text"}}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Delete Block
|
||||
```bash
|
||||
DELETE /notion/v1/blocks/{blockId}
|
||||
Notion-Version: 2025-09-03
|
||||
```
|
||||
|
||||
### Users
|
||||
|
||||
#### List Users
|
||||
```bash
|
||||
GET /notion/v1/users
|
||||
Notion-Version: 2025-09-03
|
||||
```
|
||||
|
||||
#### Get User by ID
|
||||
```bash
|
||||
GET /notion/v1/users/{userId}
|
||||
Notion-Version: 2025-09-03
|
||||
```
|
||||
|
||||
#### Get Current User (Bot)
|
||||
```bash
|
||||
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`
|
||||
|
||||
## Resources
|
||||
|
||||
- [API Introduction](https://developers.notion.com/reference/intro)
|
||||
- [Search](https://developers.notion.com/reference/post-search.md)
|
||||
- [Query Database](https://developers.notion.com/reference/post-database-query.md)
|
||||
- [Get Database](https://developers.notion.com/reference/retrieve-a-database.md)
|
||||
- [Create Database](https://developers.notion.com/reference/create-a-database.md)
|
||||
- [Get Page](https://developers.notion.com/reference/retrieve-a-page.md)
|
||||
- [Create Page](https://developers.notion.com/reference/post-page.md)
|
||||
- [Update Page](https://developers.notion.com/reference/patch-page.md)
|
||||
- [Get Block Children](https://developers.notion.com/reference/get-block-children.md)
|
||||
- [Append Block Children](https://developers.notion.com/reference/patch-block-children.md)
|
||||
- [List Users](https://developers.notion.com/reference/get-users.md)
|
||||
- [Filter Reference](https://developers.notion.com/reference/post-database-query-filter.md)
|
||||
- [LLM Reference](https://developers.notion.com/llms.txt)
|
||||
- [Version Reference](https://developers.notion.com/guides/get-started/upgrade-guide-2025-09-03)
|
||||
Reference in New Issue
Block a user