Complete guide for working with Notion API in Node.js/JavaScript projects. Use when creating, updating, fetching, or managing Notion pages, databases, and properties. Includes proper handling of rich text, database schemas, multi-select fields, dates, and complex content structures. Triggers on tasks like "create a Notion page," "update database properties," "add content to Notion," or "manage Notion workflows."
Master working with the Notion API for Node.js/JavaScript development. This skill provides patterns, tools, and references for all common Notion operations.
```typescript
// Fetch a page or database
const page = await notion_notion-fetch({
id: "page-id-or-url"
});
// Pages return markdown content and properties
// Databases return schema, data sources, and views
```
```typescript
// Single page creation
const pages = await notion_notion-create-pages({
pages: [{
properties: {
title: "My Page Title",
// Other properties based on database schema
},
content: "# Markdown content here\n\nSupports rich markdown."
}],
parent: {
data_source_id: "collection-id" // or page_id, or database_id
}
});
```
```typescript
// Update properties
await notion_notion-update-page({
page_id: "page-id",
command: "update_properties",
properties: {
title: "Updated Title",
status: "Done"
}
});
// Replace all content
await notion_notion-update-page({
page_id: "page-id",
command: "replace_content",
new_str: "# New content here"
});
// Replace specific section
await notion_notion-update-page({
page_id: "page-id",
command: "replace_content_range",
selection_with_ellipsis: "# Old heading...last paragraph.",
new_str: "# New heading\nNew content"
});
// Insert content after a section
await notion_notion-update-page({
page_id: "page-id",
command: "insert_content_after",
selection_with_ellipsis: "## Section...end of section.",
new_str: "\n## New Section\nNew content here"
});
```
```typescript
// single_select: Just use the option name
properties: {
Status: "In Progress" // Must match exact option name
}
// multi_select: Single string or comma-separated
// ❌ WRONG: ["option1", "option2"] // Don't use arrays
// ❌ WRONG: "option1,option2" // Don't use commas
// ✅ CORRECT: Need to use separate API calls or specific format
```
```typescript
// Date properties use expanded format with three keys
properties: {
"date:Due Date:start": "2025-01-30",
"date:Due Date:end": null, // Optional end date
"date:Due Date:is_datetime": 0 // 0 for date, 1 for datetime
}
```
```typescript
// Place/location properties use expanded format
properties: {
"place:Office:name": "HQ",
"place:Office:address": "123 Main St",
"place:Office:latitude": 37.7749,
"place:Office:longitude": -122.4194,
"place:Office:google_place_id": "optional-id"
}
```
Properties named "id" or "url" (case-insensitive) must be prefixed with "userDefined:":
```typescript
properties: {
"userDefined:id": "value",
"userDefined:URL": "https://example.com"
}
```
**Common mistake**: Multi-select fields have strict validation. When creating or updating pages in a database with multi_select properties:
1. **Fetch the database first** to see available options:
```typescript
const db = await notion_notion-fetch({ id: "database-id" });
// Response shows: "Tags": {"options": [{"name": "Option1"}, {"name": "Option2"}]}
```
2. **Use only valid option names**:
```typescript
properties: {
Tags: "Option1" // Single option as string
}
```
3. **For multiple options**: Currently the API has limitations. Best practice:
- Create the page with one tag
- Update it with additional tags if needed
- Or pass multiple tags separated by specific format (check database schema)
4. **Error handling**: If you get "Invalid multi_select value", check:
- Is the option name spelled exactly as shown in database?
- Are you passing a string, not an array?
- Does the database schema allow this option?
```typescript
const db = await notion_notion-fetch({
id: "database-id-or-url"
});
// Returns:
// - Database title and icon
// - Data sources (collections) within the database
// - Schema for each data source
// - Views available
```
```typescript
const db = await notion_notion-create-database({
title: [{type: "text", text: {content: "My Database"}}],
parent: {page_id: "parent-page-id"},
properties: {
"Task Name": {type: "title"},
"Status": {
type: "select",
select: {
options: [
{name: "To Do", color: "red"},
{name: "In Progress", color: "yellow"},
{name: "Done", color: "green"}
]
}
},
"Due Date": {type: "date"}
}
});
```
```typescript
await notion_notion-update-database({
database_id: "db-id",
title: [{type: "text", text: {content: "New Title"}}],
properties: {
"New Property": {type: "rich_text"},
"Property to Rename": {name: "Renamed Property"},
"Property to Delete": null // Set to null to remove
}
});
```
Toggles are created with the `▶` character followed by content that should be hidden:
```markdown
▶ Click to expand
Hidden content line 1
Hidden content line 2
- Nested list item
```
**Important**: Content after `▶` must be indented with tabs or spaces.
Content can include color and style annotations:
```markdown
Some text {color="red"} and {bold="true"}
```
```typescript
const results = await notion_notion-search({
query: "search term",
query_type: "internal" // or "user" for user search
});
// Filter by creation date
const filtered = await notion_notion-search({
query: "recent docs",
filters: {
created_date_range: {
start_date: "2025-01-01",
end_date: "2025-01-31"
}
}
});
```
```typescript
// List teams
const teams = await notion_notion-get-teams({
query: "engineering" // optional search
});
// List users
const users = await notion_notion-get-users({
query: "john", // optional search
page_size: 100
});
// Get specific user
const user = await notion_notion-get-users({
user_id: "user-id-or-self"
});
```
#### "Invalid multi_select value"
**Cause**: Option name doesn't exist or format is wrong
**Solution**:
1. Fetch database to see valid options
2. Use exact option names
3. Pass as string, not array
#### "Invalid input" / Validation error
**Cause**: Wrong property format or type
**Solution**:
1. Check property type in database schema
2. Use correct format (e.g., date properties need date:Property:start format)
3. Verify special names use userDefined: prefix
#### "Page not found"
**Cause**: Wrong ID or insufficient permissions
**Solution**:
1. Verify page/database ID is correct
2. Check you have access to the resource
3. Use full URL if ID doesn't work
#### "Unauthorized"
**Cause**: Notion integration doesn't have permission
**Solution**:
1. Verify integration is shared with the database/page
2. Check integration scopes in Notion settings
3. Re-authenticate if needed
1. **Always fetch first**: Before creating content in a database, fetch the database to understand its schema
2. **Validate option names**: Multi-select options are strictly validated—check exact spellings
3. **Use data_source_id for databases**: When a database has multiple data sources, use `data_source_id` instead of `database_id` as parent
4. **Handle IDs flexibly**: Most tools accept page IDs with or without dashes
5. **Content indentation**: Toggle/collapsible content must use tabs or spaces for indentation
6. **Break up complex updates**: Large content updates are safer when split into smaller operations
7. **Test with simple cases first**: Before complex automation, test with a single page/field
8. **Document environment**: Store Notion integration tokens securely, never in git
See [references/advanced-patterns.md](references/advanced-patterns.md) for:
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/notion-management/raw