Przejdź do treści
Biblioteka skilli
Programowanie · Integracja z narzędziem

notion

/notion

Buduje integracje z API Notion: bazy i źródła danych, strony, bloki, wyszukiwanie i OAuth, do odczytu i zapisu danych, synchronizacji z innymi narzędziami i dashboardów.

Repozytorium
skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
7
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Buduje integracje z API Notion: bazy i źródła danych, strony, bloki, wyszukiwanie i OAuth, do odczytu i zapisu danych, synchronizacji z innymi narzędziami i dashboardów.

Oryginalny opis (EN)

Build integrations with the Notion API: databases and data sources, pages, blocks, search, and OAuth. Use when tasks involve reading or writing Notion workspace data, syncing external tools with a Notion database, building dashboards from Notion content, or automating page creation and updates.

Jak działa

  1. Overview
  2. Instructions
  3. Examples
  4. Guidelines
Sekcje z nagłówków SKILL.md, w oryginale · 195 linii, 1 126 słów
Podgląd SKILL.md
---
name: notion
description: >-
  Build integrations with the Notion API: databases and data sources, pages, blocks, search, and OAuth. Use when tasks involve reading or writing Notion workspace data, syncing external tools with a Notion database, building dashboards from Notion content, or automating page creation and updates.
license: Apache-2.0
compatibility: "Python 3 with requests, or Node 18+ with @notionhq/client; API version 2026-03-11"
metadata:
  author: terminal-skills
  version: "1.1.0"
  category: productivity
  tags: "notion, api, productivity, databases, automation"
---

# Notion API Integration

## Overview

The Notion REST API (`https://api.notion.com/v1`) reads and writes pages, blocks and databases that have been shared with a connection (what Notion's UI calls an integration). Since API version `2025-09-03` a database is a container of one or more **data sources**; rows are queried and their schema read through `/v1/data_sources/{id}`, not `/v1/databases/{id}`. Version `2026-03-11` (the latest at the time of writing) renamed `archived` to `in_trash` and replaced the `after` parameter of block append with `position`. This skill uses `2026-03-11` throughout.

## Instructions

### Authentication

Create a connection at https://www.notion.so/my-integrations, copy its token, and share each target page or database with it (page menu, Connections). Keep the token in an environment variable:

```bash
export NOTION_TOKEN="ntn_..."   # from the connection's Configuration tab
```

For apps used by many workspaces, create a public connection and use OAuth 2.0: send the user to `https://api.notion.com/v1/oauth/authorize?owner=user&client_id=...&redirect_uri=...&response_type=code`, then POST the returned `code` (`grant_type=authorization_code`, same `redirect_uri`) to `https://api.notion.com/v1/oauth/token` with HTTP Basic auth `client_id:client_secret`. Each user authorizes separately. The Notion-Version header is required on every request.

### Client setup and rate limits

```python
"""notion_client.py — shared request helper with retry on 429/529/503."""
import os
import time
import requests

API = "https://api.notion.com/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['NOTION_TOKEN']}",
    "Notion-Version": "2026-03-11",
    "Content-Type": "application/json",
}

def call(method: str, path: str, **kwargs) -> dict:
    """Send a request; wait for Retry-After on HTTP 429 or 529, back off on 503 for GET."""
    for attempt in range(5):
        resp = requests.request(method, f"{API}{path}", headers=HEADERS, timeout=30, **kwargs)
        if resp.status_code in (429, 529):
            time.sleep(int(resp.headers.get("Retry-After", 2 ** attempt)))
            continue
        if resp.status_code == 503 and method == "GET":
            time.sleep(2 ** attempt)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"Notion request kept failing: {method} {path}")
```

Limits: each connection gets 180 requests per minute (about 3 per second; 600 per minute on Business and Enterprise workspaces), data source queries about 3 per second, and a separate workspace-wide budget exists. Do not retry a failed write blindly after a 503: check whether it was applied first. At most 100 blocks go in one append request, and a request body is limited in size.

### Find the data source of a database

A database ID (from the URL) is not enough for queries. Fetch its data sources once and store the ID:

```python
def get_data_source_id(database_id: str) -> str:
    """Return the first data source ID of a database (most databases have one)."""
    db = call("GET", f"/databases/{database_id}")
    return db["data_sources"][0]["id"]
```

Search also returns data source objects: `{"filter": {"property": "object", "value": "data_source"}}` (`"database"` was the value before `2025-09-03`).

### Query, create and update rows

```python
def query_data_source(data_source_id: str, filter_obj: dict = None, sorts: list = None) -> list:
    """Return all pages of a data source matching the filter, following the cursor."""
    body = {"page_size": 100}
    if filter_obj:
        body["filter"] = filter_obj
    if sorts:
        body["sorts"] = sorts
    pages = []
    while True:
        data = call("POST", f"/data_sources/{data_source_id}/query", json=body)
        pages.extend(data["results"])
        if not data.get("has_more"):
            return pages
        body["start_cursor"] = data["next_cursor"]

def create_page(data_source_id: str, properties: dict, children: list = None) -> dict:
    """Create a row (page) in a data source."""
    body = {"parent": {"data_source_id": data_source_id}, "properties": properties}
    if children:
        body["children"] = children
    return call("POST", "/pages", json=body)

def update_page(page_id: str, properties: dict) -> dict:
    """Change properties of an existing page."""
    return call("PATCH", f"/pages/{page_id}", json={"properties": properties})

def trash_page(page_id: str) -> dict:
    """Move a page to the trash (restorable from the Notion UI)."""
    return call("PATCH", f"/pages/{page_id}", json={"in_trash": True})
```

Querying returns at most 10,000 results per query; narrow the filter for bigger sets. Example filter: `{"property": "Status", "select": {"equals": "In Progress"}}`; combine with `{"and": [...]}` or `{"or": [...]}`.

### Property values

```python
properties = {
    "Name": {"title": [{"text": {"content": "Fix login redirect"}}]},      # every data source has one title property
    "Description": {"rich_text": [{"text": {"content": "Redirect loops on Safari"}}]},
    "Status": {"select": {"name": "In Progress"}},
    "Tags": {"multi_select": [{"name": "frontend"}, {"name": "urgent"}]},
    "Story Points": {"number": 5},
    "Due Date": {"date": {"start": "2026-11-15", "end": "2026-11-20"}},
    "Done": {"checkbox": False},
    "Link": {"url": "https://github.com/acme-web/shop/issues/412"},
    "Assignee": {"people": [{"id": "0d0ca9b1-6b1e-4c2b-8f0a-2f2a1e7d9c11"}]},
    "Project": {"relation": [{"id": "5a1f3c1e-9b0a-4d3e-8c52-7d1b2f9e0a34"}]},
}
```

Property names must match the data source schema (`GET /v1/data_sources/{id}` shows it). A `status` property takes `{"status": {"name": "..."}}` with an option that already exists.

### Blocks

```python
def append_blocks(page_id: str, blocks: list, after_block_id: str = None) -> dict:
    """Append blocks to a page or block (max 100); optionally insert after a given block."""
    body = {"children": blocks}
    if after_block_id:
        body["position"] = {"type": "after_block", "after_block": {"id": after_block_id}}
    return call("PATCH", f"/blocks/{page_id}/children", json=body)

blocks = [
    {"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Sprint 42 summary"}}]}},
    {"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Focus: checkout performance."}}]}},
    {"type": "bulleted_list_item", "bulleted_list_item": {"rich_text": [{"text": {"content": "Shipped payment retry"}}]}},
    {"type": "to_do", "to_do": {"rich_text": [{"text": {"content": "Write migration notes"}}], "checked": False}},
    {"type": "code", "code": {"rich_text": [{"text": {"content": "npm run build"}}], "language": "shell"}},
]
```

`position` also accepts `{"type": "start"}` and `{"type": "end"}` (the default). To read a page's content, `GET /blocks/{page_id}/children?page_size=100` and follow `next_cursor`; nested blocks (toggles, columns) have `has_children: true` and need their own call.

### Search

```python
def search(query: str, kind: str = "page") -> list:
    """kind is 'page' or 'data_source'."""
    body = {"query": query, "filter": {"property": "object", "value": kind}}
    return call("POST", "/search", json=body)["results"]
```

## Examples

### Example 1: "Sync GitHub issues into my Notion tracker"

```python
# uses the helpers defined above (call, get_data_source_id, query_data_source, create_page, update_page)
ds = get_data_source_id("b6a4e1c2d3f84a7e9f10a2b3c4d5e6f7")
existing = {p["properties"]["Issue #"]["number"]: p["id"]
            for p in query_data_source(ds) if p["properties"]["Issue #"]["number"]}

issues = [{"number": 412, "title": "Fix login redirect", "state": "open", "url": "https://github.com/acme-web/shop/issues/412"}]
for i in issues:
    props = {
        "Name": {"title": [{"text": {"content": i["title"]}}]},
        "Issue #": {"number": i["number"]},
        "Status": {"select": {"name": "Open" if i["state"] == "open" else "Closed"}},
        "URL": {"url": i["url"]},
    }
    if i["number"] in existing:
        update_page(existing[i["number"]], props)
    else:
        create_page(ds, props)
```

Result: issue 412 appears as a new row, or its existing row is updated, with no duplicates.

### Example 2: "Add a standup note to today's meeting page"

```python
append_blocks("9f2c7a10b4e84d6c8a31c5d2e7f90b12", [
    {"type": "heading_3", "heading_3": {"rich_text": [{"text": {"content": "Standup 2026-11-03"}}]}},
    {"type": "bulleted_list_item", "bulleted_list_item": {"rich_text": [{"text": {"content": "Blocked on staging DB access"}}]}},
])
```

The call returns the new blocks; the heading and bullet appear at the end of the page.

## Guidelines

- Share every page or database with the connection first; otherwise the API answers `object_not_found`, which looks like a wrong ID.
- Code written for versions before `2025-09-03` (`/databases/{id}/query`, `parent.database_id`, search `value: "database"`) breaks on the new version; do not mix the two styles. Use the JavaScript SDK v5.12.0 or later for `2026-03-11`.
- Use `in_trash` (not `archived`) to trash pages, blocks and data sources on `2026-03-11`; a page response also has `is_archived`.
- Prefer server-side filters over fetching all rows. Formula, rollup and some other property types are read-only through the API.
- Rich text comes as arrays of segments; join their `plain_text` to get text.
- Keep the token in an environment variable or secret manager, never in code or a repository.
Pliki w paczce (2)
  • SKILL.md 10 KB
  • _scores.json 1 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · TerminalSkills/skills100Apache-2.0
magnus919/agent-skills100MIT
OpenHands/extensions100MIT
apideck-libraries/api-skills100Apache-2.0
mhycheung/open-science100MIT
HelixDevelopment/agent100MIT
G1Joshi/Agent-Skills100MIT
Orkas-AI/Orkas-Awesome-AgentSkills100MIT
intentic/intentic96MIT

Migawka bazy z 13.11.2026 · wersja paczki ad8779a70873 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100notion-tool
    Integruje się z Notion przez API: wyszukuje, pobiera, tworzy i aktualizuje strony oraz bazy danych, w tym dodaje wiersze do baz.
  • 100notion-api
    Wyszukuje, czyta i zapisuje strony, bazy danych oraz bloki w Notion przez API, w tym dodawanie wierszy i dopisywanie treści do stron.
  • 90Notion API Integration
    Buduje i naprawia integracje z API Notion: bazy danych, strony, bloki, filtry, pliki, webhooki i masowe importy.
  • 100notion-cli
    Obsługuje Notion przez binarkę Go 4ier/notion-cli: wyszukiwanie, zapytania do baz danych, odczyt stron i eksport danych z poziomu terminala.
  • 100notion-core-workflow-b
    Tworzy i aktualizuje strony oraz bloki Notion z kluczem idempotencji, porównaniem semantycznym zmian i weryfikacją przez ponowny odczyt zapisanej treści.
  • 100notion-hub
    Czyta i zapisuje dane Notion w Pythonie przez SDK notion-client: wyszukiwanie, operacje na stronach z konwersją Markdown i bloków, schematy baz oraz zapytania do nich.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.