Notion Api

Notion API is a community skill for integrating with the Notion workspace platform through its REST API, covering database queries, page creation, content blocks, property updates, and automation workflows for Notion workspace management.

What Is This?

Overview

Notion API provides patterns for programmatically managing content in Notion workspaces. It covers database querying with filter and sort parameters for retrieving structured records, page creation with rich content blocks including text, headings, and lists, property updates for modifying database entries with typed fields like select, date, and relation, and block manipulation for appending and rearranging page content. The skill enables developers to build integrations that synchronize Notion data with external systems, automate content workflows, and build dashboards backed by Notion databases.

Who Should Use This

This skill serves developers building integrations between Notion and external tools like CRMs or project trackers, teams automating repetitive Notion workflows such as status updates, and product builders using Notion databases as a backend for internal tools.

Why Use It?

Problems It Solves

Manually updating Notion databases with data from external systems is time-consuming for recurring tasks. Building page content programmatically requires understanding the block structure Notion uses internally. Querying Notion databases with complex filters needs proper API parameter construction. Synchronizing data between Notion and external platforms demands structured integration patterns.

Core Highlights

Database client queries Notion databases with typed filters and pagination handling. Page builder constructs rich content from structured block definitions. Property manager updates database entries with validation for field types. Search endpoint finds pages and databases across the workspace by title.

How to Use It?

Basic Usage

import requests
import os

class NotionClient:
    def __init__(self):
        self.token = os.environ[
            "NOTION_API_KEY"]
        self.base = (
            "https://api.notion.com/v1")
        self.headers = {
            "Authorization":
                f"Bearer {self.token}",
            "Content-Type":
                "application/json",
            "Notion-Version": "2022-06-28"}

    def query_database(
            self, database_id: str,
            filter_obj: dict = None
            ) -> list:
        url = (f"{self.base}/databases/"
               f"{database_id}/query")
        payload = {}
        if filter_obj:
            payload["filter"] = filter_obj
        resp = requests.post(
            url, json=payload,
            headers=self.headers)
        return resp.json()["results"]

    def create_page(
            self, database_id: str,
            properties: dict) -> dict:
        url = f"{self.base}/pages"
        payload = {
            "parent": {"database_id":
                        database_id},
            "properties": properties}
        resp = requests.post(
            url, json=payload,
            headers=self.headers)
        return resp.json()

client = NotionClient()
tasks = client.query_database(
    "db_id_here",
    {"property": "Status",
     "select": {"equals": "Active"}})
print(f"Active tasks: {len(tasks)}")

Real-World Examples

import requests
import os
from datetime import datetime

class NotionSyncManager:
    def __init__(self, client):
        self.client = client

    def sync_records(
            self, database_id: str,
            records: list[dict]) -> dict:
        created, updated = 0, 0
        existing = self.client\
            .query_database(database_id)
        existing_map = {}
        for page in existing:
            title_prop = page["properties"]\
                .get("Name", {})
            title_list = title_prop.get(
                "title", [])
            if title_list:
                name = title_list[0][
                    "plain_text"]
                existing_map[name] = (
                    page["id"])
        for record in records:
            props = self._build_properties(
                record)
            if record["name"] in (
                    existing_map):
                self._update_page(
                    existing_map[
                        record["name"]],
                    props)
                updated += 1
            else:
                self.client.create_page(
                    database_id, props)
                created += 1
        return {"created": created,
                "updated": updated}

    def _build_properties(
            self, record: dict) -> dict:
        return {
            "Name": {"title": [{
                "text": {"content":
                    record["name"]}}]},
            "Status": {"select": {
                "name":
                    record.get("status",
                               "New")}}}

    def _update_page(
            self, page_id: str,
            properties: dict) -> None:
        url = (f"{self.client.base}"
               f"/pages/{page_id}")
        requests.patch(
            url,
            json={"properties": properties},
            headers=self.client.headers)

sync = NotionSyncManager(client)
result = sync.sync_records("db_id", [
    {"name": "Task A", "status": "Done"},
    {"name": "Task B", "status": "Active"}])
print(f"Synced: {result}")

Advanced Tips

Implement cursor-based pagination for database queries that return more than 100 results per request. Use the Notion search endpoint to find databases by title before querying them by ID. Cache database schema information to validate property types before constructing update payloads.

When to Use It?

Use Cases

Build a CRM sync tool that mirrors customer records between Notion databases and Salesforce. Create an automated reporting pipeline that generates weekly summary pages from project tracker databases. Implement a content publishing workflow that creates blog posts from Notion pages exported to a static site generator.

Related Topics

Notion workspace automation, REST API integration, content management systems, data synchronization, and productivity tools.

Important Notes

Requirements

A Notion integration token with access to the target workspace. Python with the requests library for API calls. Database and page IDs for the target resources.

Usage Recommendations

Do: handle pagination for all database queries since results are limited to 100 per request. Use the correct property type format when creating or updating pages. Implement rate limiting to stay within three requests per second.

Don't: poll databases in tight loops for change detection when webhook alternatives exist. Store large binary files as page content when external storage with Notion links is more efficient. Assume property names are stable across workspace reorganizations without validation.

Limitations

The Notion API rate limit of three requests per second constrains bulk operations on large databases. Some Notion features like inline databases are not fully supported through the API. Real-time change notifications require polling since Notion does not provide native webhook push events.

FAQ

Q: How can I use the Notion Api Skill to automate tasks in my Notion workspace?

The Notion Api Skill on Happycapy allows you to automate workflows such as creating, updating, and organizing pages or databases in Notion using AI agent capabilities.

Q: Does this Skill support integration with other Skills on Happycapy?

Yes, the Notion Api Skill can be combined with other Skills in Happycapy to create multi-step automations and streamline your productivity.

Q: Can the Notion Api Skill help me sync content between Notion and other platforms?

With the power of AI agent automation, you can use this Skill to sync content between Notion and various platforms supported by Happycapy Skills.

Q: What types of Notion content can I manage using this Skill?

You can manage pages, databases, and their content within Notion through this Skill, leveraging the flexibility of Happycapy Skills and AI agent workflows.

Q: Is it possible to trigger Notion updates based on external events using this Skill?

Yes, you can set up AI agent automations in Happycapy to trigger Notion updates when specific external events occur, making your workflows more dynamic.