--- name: integracion-api-notion description: Guía de referencia con patrones de código Python para construir integraciones con la API REST de Notion: consultar y actualizar bases de datos, crear páginas, manipular bloques, buscar contenido y gestionar paginación y rate limits. license: Apache-2.0 metadata: id: 05204f32 slug: integracion-api-notion titulo: "Integración API Notion" servicio: Automatizaciones categoria_recurso: Automatizacion tipo: referencia nivel: intermedio idioma: es idioma_original: en acceso: gratis precio_eur: 0 plataformas: [Notion, Python] dependencias: [requests, NOTION_TOKEN] licencia: { spdx: Apache-2.0, redistribuible: true, uso_comercial: true } fuente: repo: TerminalSkills/skills url: https://github.com/TerminalSkills/skills/tree/main/skills/notion commit: 77fa015 autor: TerminalSkills nombre_original: notion duplicados_en: [] seguridad: { veredicto: seguro, riesgo: bajo, escaneado: "2026-06-14", motor: "grep-estatico+auditor-llm" } ficha: que_hace: "Proporciona patrones de código listos para usar que cubren las operaciones principales de la API de Notion: bases de datos, páginas, bloques, búsqueda y OAuth." como_lo_hace: "Implementa funciones Python con la librería requests que encapsulan los endpoints REST de Notion, incluyendo paginación automática, reintentos con backoff ante rate limits y ejemplos de sincronización de datos externos." content_hash: "05204f32e5bea7db32fce5e0a0d21c8850bcc8195b72e0ed9b565f76e61fe856" version: 1.0.0 --- # Notion API Integration Build automations and integrations with Notion workspaces using the official REST API. ## Authentication ### Internal Integration (own workspace) Create an integration at https://www.notion.so/my-integrations, copy the token, and share target pages/databases with the integration. ```bash export NOTION_TOKEN="ntn_..." ``` ### Public Integration (OAuth) For multi-user apps, implement the OAuth flow using the authorization URL `https://api.notion.com/v1/oauth/authorize` and exchange the code at `https://api.notion.com/v1/oauth/token` with Basic auth (base64-encoded `client_id:client_secret`). ## Core API Patterns All requests use `Notion-Version: 2022-06-28` header and Bearer token auth. ### Database Operations ```python """notion_db.py — Query, create, and update Notion databases.""" import requests API = "https://api.notion.com/v1" HEADERS = { "Authorization": "Bearer ntn_...", "Notion-Version": "2022-06-28", "Content-Type": "application/json", } def query_database(database_id: str, filter_obj: dict = None, sorts: list = None) -> list: """Query a Notion database with optional filters and sorting. Args: database_id: UUID of the database (from URL or API). filter_obj: Notion filter object for narrowing results. sorts: List of sort objects (property + direction). Returns: List of page objects matching the query. """ body = {} if filter_obj: body["filter"] = filter_obj if sorts: body["sorts"] = sorts pages = [] has_more = True start_cursor = None while has_more: if start_cursor: body["start_cursor"] = start_cursor resp = requests.post(f"{API}/databases/{database_id}/query", json=body, headers=HEADERS) data = resp.json() pages.extend(data["results"]) has_more = data.get("has_more", False) start_cursor = data.get("next_cursor") return pages def create_page(database_id: str, properties: dict, children: list = None) -> dict: """Create a new page (row) in a Notion database. Args: database_id: Target database UUID. properties: Property values matching database schema. children: Optional list of block objects for page content. """ body = { "parent": {"database_id": database_id}, "properties": properties, } if children: body["children"] = children resp = requests.post(f"{API}/pages", json=body, headers=HEADERS) return resp.json() def update_page(page_id: str, properties: dict) -> dict: """Update properties of an existing page. Args: page_id: UUID of the page to update. properties: Property values to change. """ resp = requests.patch(f"{API}/pages/{page_id}", json={"properties": properties}, headers=HEADERS) return resp.json() ``` ### Property Types Common property value formats for `create_page` and `update_page`: ```python # Property value examples for database pages properties = { # Title (required — every database has one title property) "Name": {"title": [{"text": {"content": "New task"}}]}, # Rich text "Description": {"rich_text": [{"text": {"content": "Details here"}}]}, # Select (single choice) "Status": {"select": {"name": "In Progress"}}, # Multi-select "Tags": {"multi_select": [{"name": "frontend"}, {"name": "urgent"}]}, # Number "Story Points": {"number": 5}, # Date (with optional end for ranges) "Due Date": {"date": {"start": "2025-03-15", "end": "2025-03-20"}}, # Checkbox "Done": {"checkbox": True}, # URL / Email / People / Relation "Link": {"url": "https://example.com"}, "Assignee": {"people": [{"id": "user-uuid-here"}]}, "Project": {"relation": [{"id": "related-page-uuid"}]}, } ``` ### Block Operations Pages are made of blocks. Append, read, or delete blocks to build page content: ```python def append_blocks(page_id: str, blocks: list) -> dict: """Append content blocks to a page. Args: page_id: UUID of the page. blocks: List of block objects to append. """ resp = requests.patch(f"{API}/blocks/{page_id}/children", json={"children": blocks}, headers=HEADERS) return resp.json() # Block examples blocks = [ # Heading {"type": "heading_2", "heading_2": { "rich_text": [{"text": {"content": "Sprint Summary"}}] }}, # Paragraph {"type": "paragraph", "paragraph": { "rich_text": [{"text": {"content": "This sprint focused on..."}}] }}, # Bulleted list {"type": "bulleted_list_item", "bulleted_list_item": { "rich_text": [{"text": {"content": "Shipped auth module"}}] }}, # To-do {"type": "to_do", "to_do": { "rich_text": [{"text": {"content": "Write tests"}}], "checked": False, }}, # Code block {"type": "code", "code": { "rich_text": [{"text": {"content": "console.log('hello')"}}], "language": "javascript", }}, ] ``` ### Search ```python def search_workspace(query: str, object_type: str = None) -> list: """Search across all pages and databases in the workspace. Args: query: Search text. object_type: Optional filter — "page" or "database". """ body = {"query": query} if object_type: body["filter"] = {"value": object_type, "property": "object"} resp = requests.post(f"{API}/search", json=body, headers=HEADERS) return resp.json()["results"] ``` ## Pagination All list endpoints return max 100 items. Always paginate: ```python def get_all_blocks(block_id: str) -> list: """Retrieve all child blocks, handling pagination. Args: block_id: UUID of the parent block or page. """ blocks, cursor = [], None while True: params = {"page_size": 100} if cursor: params["start_cursor"] = cursor resp = requests.get(f"{API}/blocks/{block_id}/children", params=params, headers=HEADERS) data = resp.json() blocks.extend(data["results"]) if not data.get("has_more"): break cursor = data["next_cursor"] return blocks ``` ## Rate Limits - **3 requests per second** per integration - Implement exponential backoff on 429 responses - Batch operations where possible (append multiple blocks in one call) ```python import time def safe_request(method, url, **kwargs): """Make a rate-limit-aware request with retry.""" for attempt in range(5): resp = requests.request(method, url, headers=HEADERS, **kwargs) if resp.status_code == 429: wait = int(resp.headers.get("Retry-After", 2 ** attempt)) time.sleep(wait) continue resp.raise_for_status() return resp.json() raise Exception("Rate limit exceeded after 5 retries") ``` ## Common Patterns ### Sync External Data into Notion ```python def sync_github_issues(database_id: str, issues: list[dict]): """Sync GitHub issues into a Notion database, updating existing or creating new. Args: database_id: Target Notion database. issues: List of dicts with keys: number, title, state, labels, url. """ # Get existing pages to avoid duplicates existing = query_database(database_id) existing_numbers = {} for page in existing: num_prop = page["properties"].get("Issue #", {}) if num_prop.get("number"): existing_numbers[int(num_prop["number"])] = page["id"] for issue in issues: props = { "Name": {"title": [{"text": {"content": issue["title"]}}]}, "Issue #": {"number": issue["number"]}, "Status": {"select": {"name": "Open" if issue["state"] == "open" else "Closed"}}, "Labels": {"multi_select": [{"name": l} for l in issue["labels"]]}, "URL": {"url": issue["url"]}, } if issue["number"] in existing_numbers: update_page(existing_numbers[issue["number"]], props) else: create_page(database_id, props) ``` ## Guidelines - Always share pages/databases with your integration before accessing them - Use database queries with filters instead of fetching all pages and filtering client-side - Notion API returns rich text as arrays of text objects -- always join them for plain text - Block children can be nested (toggle lists, columns) -- recurse when reading full pages - The API does not support creating databases with all property types -- some (like rollup, formula) must be configured in the Notion UI - Archive pages instead of deleting them (`update_page(id, {"archived": True})`)