orthogonal-sh/notion

Notion

Create pages, search content, fetch data, and add content to your Notion workspace. Connect your Notion account to manage pages, databases, and content programmatically.

Requirements

• Install the orth CLI
• Connect your Notion workspace at https://orthogonal.com/dashboard/integrations
• OAuth connection must be active (HTTP 428 response means not connected)

Actions

Create Page

Create a new page in your Notion workspace.

orth run notion /create-page --body '{
  "title": "Meeting Notes",
  "parent_id": "parent-page-or-database-id"
}'

Parameters:

• title (required) - Page title
• parent_id (required) - Parent page or database ID where page will be created
• icon - Page icon (emoji or external URL)
• cover - Cover image URL for the page

Search

Search for pages and databases in your Notion workspace.

orth run notion /search --body '{
  "query": "meeting notes",
  "filter_value": "page"
}'

Parameters:

• query - Search query text
• filter_value - Filter results by type (page, database)
• direction - Sort direction (ascending, descending)
• timestamp - Property to sort by timestamp
• page_size - Number of results per page
• start_cursor - Cursor for pagination
• filter_property - Property to filter by

Fetch Data

Retrieve pages and databases from your Notion workspace.

orth run notion /fetch-data --body '{
  "get_pages": true,
  "page_size": 20
}'

Parameters:

• query - Optional search query
• get_pages - Retrieve pages (only one of get_pages, get_databases, get_all can be true)
• get_databases - Retrieve databases (only one of get_pages, get_databases, get_all can be true)
• get_all - Retrieve both pages and databases (only one of get_pages, get_databases, get_all can be true)
• page_size - Number of items per page

Add Content

Add content blocks to an existing Notion page.

orth run notion /add-content --body '{
  "parent_block_id": "page-block-id",
  "content_blocks": [
    {"type": "paragraph", "text": "This is a paragraph with **markdown** support."},
    {"type": "heading_1", "text": "Main Heading"}
  ]
}'

Parameters:

• parent_block_id (required) - ID of the parent block/page to add content to
• content_blocks (required) - Array of content blocks to add (supports markdown)
• after - Insert content after specific block ID

Usage Examples

Create a new project page:

orth run notion /create-page -b '{"title":"Q1 Project Plan","parent_id":"abc123-def456-ghi789","icon":"📋"}'

Search for meeting notes:

orth run notion /search -b '{"query":"team meeting","filter_value":"page","page_size":10}'

Get all pages:

orth run notion /fetch-data -b '{"get_pages":true,"page_size":50}'

Get all databases:

orth run notion /fetch-data -b '{"get_databases":true}'

Add structured content:

orth run notion /add-content -b '{"parent_block_id":"page123","content_blocks":[{"type":"heading_2","text":"Action Items"},{"type":"paragraph","text":"- Complete user testing\n- Update documentation\n- Schedule follow-up meeting"}]}'

Add content with markdown:

orth run notion /add-content -b '{"parent_block_id":"page456","content_blocks":[{"type":"paragraph","text":"This **important** note has [a link](https://example.com) and `inline code`."}]}'

Content Block Types

When adding content, you can use these block types:

• paragraph - Regular text paragraph
• heading_1 - Main heading (H1)
• heading_2 - Section heading (H2)
• heading_3 - Subsection heading (H3)
• bulleted_list_item - Bullet point
• numbered_list_item - Numbered list item
• to_do - Checkbox item
• code - Code block
• quote - Block quote

Error Handling

• HTTP 428 - Notion integration not connected. Visit https://orthogonal.com/dashboard/integrations to connect your workspace
• 400 Bad Request - Invalid parameters or malformed content blocks
• 401 Unauthorized - Invalid or expired Notion token
• 403 Forbidden - Insufficient permissions for page or database
• 404 Not Found - Page, database, or block does not exist
• 429 Rate Limited - Notion API rate limit exceeded
• validation_error - Invalid block content or structure

Tips

• Get parent_id from existing pages by using the search or fetch-data actions
• Page IDs can be found in the URL when viewing a page in Notion
• Content blocks support markdown formatting (bold, italic, links, code)
• Use only one of get_pages, get_databases, or get_all in fetch-data
• Icons can be emoji characters or external image URLs
• Search is case-insensitive and searches titles and content
• Pagination uses start_cursor from previous responses
• Block IDs are returned when creating pages or adding content