Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Notion API · mkurman | DecimalAI

mkurman/notion-api

SkillScore100Maintained

This skill provides comprehensive instructions for interacting with the Notion API via REST calls. This skill should be used whenever the user asks to interact with Notion, including reading, creating, updating, or deleting pages, databases, blocks, comments, or any other Notion content. The skill covers authentication, all available endpoints, pagination, error handling, and best practices.

productivityby mkurman

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Knowledge Management pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/mkurman-notion-api/SKILL.md

decimalai skills pull mkurman-notion-api --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/mkurman-notion-api/SKILL.md https://app.decimal.ai/s/mkurman-notion-api/SKILL.md

Raw file: /s/mkurman-notion-api/SKILL.md ↗ · machine-readable summary at /s/mkurman-notion-api.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

23 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 8d ago

Yes — +43% lift · at higher cost+232% tokens0% turns100% of whole cases pass with skill (23/23)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-01	✗→✓	▲ Improved	424%	0%
case-02	✗→✓	▲ Improved	450%	0%
case-03	✗→✓	▲ Improved	323%	0%
case-04	✗→✓	▲ Improved	33%	0%
case-05	✗→✓	▲ Improved	165%	0%

Showing 5 of 23 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/3/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

mkurman / zorai

skills/productivity/agent-skills/notion-api/SKILL.md

View on GitHub ↗

License MITImported 8/3/2026Version v1

Skill contents

SKILL.md

|-------| | Maximum block elements per payload | 1000 | | Maximum payload size | 500KB | | Rich text content | 2000 characters | | URLs | 2000 characters | | Equations | 1000 characters | | Email addresses | 200 characters | | Phone numbers | 200 characters | | Multi-select options | 100 items | | Relations | 100 related pages | | People mentions | 100 users | | Block arrays per request | 100 elements |

Confirmation for Destructive Operations

IMPORTANT: Before executing any operation that modifies or deletes data, ask the user for confirmation. This includes:

Updating pages or blocks
Deleting/archiving pages or blocks
Modifying database schemas
Creating pages (if multiple or in batch)
Any bulk operations

For a logical group of related operations, a single confirmation is sufficient.

Core API Endpoints

Search

Search across all accessible pages and databases:

bash
curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search term",
    "filter": {"property": "object", "value": "page"},
    "sort": {"direction": "descending", "timestamp": "last_edited_time"},
    "page_size": 100
  }' | jq

Filter values: "page" or "data_source" (or omit for both)

Pages

Retrieve a Page

bash
curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Note: This returns page properties, not content. For content, use "Retrieve block children" with the page ID.

Create a Page

bash
curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "properties": {
      "title": {
        "title": [{"text": {"content": "Page Title"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Paragraph content"}}]
        }
      }
    ]
  }' | jq

Parent options:

{"page_id": "..."} - Create under a page
{"database_id": "..."} - Create in a database (legacy)
{"data_source_id": "..."} - Create in a data source (API v2025-09-03+)

Update a Page

bash
curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "title": {"title": [{"text": {"content": "Updated Title"}}]}
    },
    "icon": {"type": "emoji", "emoji": "📝"},
    "archived": false
  }' | jq

Additional update options: cover, is_locked, in_trash

Archive (Delete) a Page

bash
curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' | jq

Retrieve a Page Property Item

For properties with more than 25 references:

bash
curl -s "https://api.notion.com/v1/pages/{page_id}/properties/{property_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Blocks (Page Content)

Retrieve Block Children

bash
curl -s "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Use the page ID as block_id to get page content. Check has_children on each block for nested content.

Append Block Children

bash
curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [{"type": "text", "text": {"content": "New Section"}}]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Content here"}}]
        }
      }
    ]
  }' | jq

Maximum 100 blocks per request, up to 2 levels of nesting.

Position options in request body:

Default: appends to end
"position": {"type": "start"} - Insert at beginning
"position": {"type": "after_block", "after_block": {"id": "block-id"}} - Insert after specific block

Retrieve a Block

bash
curl -s "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Update a Block

bash
curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "paragraph": {
      "rich_text": [{"type": "text", "text": {"content": "Updated content"}}]
    }
  }' | jq

The update replaces the entire value for the specified field.

Delete a Block

bash
curl -s -X DELETE "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Moves block to trash (can be restored).

Databases

Retrieve a Database

bash
curl -s "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Returns database structure including data sources and properties.

Query a Database

bash
curl -s -X POST "https://api.notion.com/v1/databases/{database_id}/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "Status",
      "select": {"equals": "Done"}
    },
    "sorts": [
      {"property": "Created", "direction": "descending"}
    ],
    "page_size": 100
  }' | jq

See references/filters-and-sorts.md for comprehensive filter and sort documentation.

Create a Database

bash
curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "title": [{"type": "text", "text": {"content": "My Database"}}],
    "is_inline": true,
    "initial_data_source": {
      "properties": {
        "Name": {"title": {}},
        "Status": {
          "select": {
            "options": [
              {"name": "To Do", "color": "red"},
              {"name": "In Progress", "color": "yellow"},
              {"name": "Done", "color": "green"}
            ]
          }
        },
        "Due Date": {"date": {}}
      }
    }
  }' | jq

Update a Database

bash
curl -s -X PATCH "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "title": [{"text": {"content": "Updated Title"}}],
    "description": [{"text": {"content": "Database description"}}]
  }' | jq

Data Sources (API v2025-09-03+)

Data sources are individual tables within a database. As of API version 2025-09-03, databases can contain multiple data sources.

Create a Data Source

bash
curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "database_id", "database_id": "database-id"},
    "title": [{"type": "text", "text": {"content": "New Data Source"}}],
    "properties": {
      "Name": {"title": {}},
      "Description": {"rich_text": {}}
    }
  }' | jq

Users

List All Users

bash
curl -s "https://api.notion.com/v1/users?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Retrieve a User

bash
curl -s "https://api.notion.com/v1/users/{user_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Retrieve Bot User (Self)

bash
curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Comments

Retrieve Comments

bash
curl -s "https://api.notion.com/v1/comments?block_id={block_id}&page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Use a page ID as block_id for page-level comments.

Create a Comment

On a page:

bash
curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "page-id"},
    "rich_text": [{"type": "text", "text": {"content": "Comment content"}}]
  }' | jq

Reply to a discussion:

bash
curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "discussion_id": "discussion-id",
    "rich_text": [{"type": "text", "text": {"content": "Reply content"}}]
  }' | jq

Note: The API cannot start new inline discussion threads or edit/delete existing comments.

Pagination

Paginated endpoints return:

has_more: Boolean indicating more results exist
next_cursor: Cursor for the next page
results: Array of items

To iterate through all results:

Make the initial request (omit start_cursor)
Check has_more in the response
If true, extract next_cursor and include it as start_cursor in the next request
Repeat until has_more is false

Example request with cursor:

json
{
  "page_size": 100,
  "start_cursor": "v1%7C..."
}

Error Handling

| HTTP Status | Code | Description | |-------------|------|-------------| | 400 | invalid_json | Request body is not valid JSON | | 400 | invalid_request_url | URL is malformed | | 400 | invalid_request | Request is not supported | | 400 | validation_error | Request body doesn't match expected schema | | 400 | missing_version | Missing Notion-Version header | | 401 | unauthorized | Invalid bearer token | | 403 | restricted_resource | Token lacks permission | | 404 | object_not_found | Resource doesn't exist or not shared with integration | | 409 | conflict_error | Data collision during transaction | | 429 | rate_limited | Rate limit exceeded (check Retry-After header) | | 500 | internal_server_error | Unexpected server error | | 503 | service_unavailable | Notion unavailable or 60s timeout exceeded | | 503 | database_connection_unavailable | Database unresponsive | | 504 | gateway_timeout | Request timeout |

Best Practices

Store IDs: When creating pages/databases, store the returned IDs for future updates
Use Property IDs: Reference properties by ID rather than name for stability
Batch Operations: Aggregate multiple small operations into fewer requests
Respect Rate Limits: Implement exponential backoff for 429 responses
Check has_more: Always handle pagination for list endpoints
Validate Before Updates: Retrieve current state before making updates
Use Environment Variables: Never hardcode API keys
Handle Errors Gracefully: Check response status codes and error messages
Schema Size: Keep database schemas under 50KB for optimal performance
Properties Limit: Properties with >25 page references require separate retrieval

References

For detailed documentation on specific topics, see:

references/block-types.md - All supported block types and their structures
references/property-types.md - Database property types and value formats
references/filters-and-sorts.md - Database query filter and sort syntax
references/rich-text.md - Rich text object structure and annotations

Want to see if mkurman/notion-api would activate on your phrasing? Try it before you install — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/21/2026, 22:40 UTC · 23 cases

Lift

+43%

100% vs 57%

Agent turns

1.0 vs 1.0

Tokens

+232%

5,041.87 vs 1,518.52

fail → pass · 10pass → pass · 13

Per-case results (23)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 Look up any accessible workspace pages containing 'Q3 Roadmap' in Notion using a terminal curl command. Provide the API request snippet formatted to pipe into jq.	fail→pass	4,382	3,030	-31%	1	1	0%	901	4,721	+424%	0	0	—
case-02 I need to archive an obsolete page with ID 'b1234567-89ab-cdef-0123-456789abcdef' in Notion. Please generate the appropriate API call to send this update.	fail→pass	4,933	5,523	+12%	1	1	0%	952	5,239	+450%	0	0	—
case-03 Can you write a curl request to query my task database with ID 'db_tasks_123'? I need to fetch items where the 'Status' property is 'Done', ordered by creation time descending.	fail→pass	6,174	5,002	-19%	1	1	0%	1,207	5,105	+323%	0	0	—
case-04 I want to add a new heading block to the top of an existing page block 'blk_987654' in Notion rather than appending it at the end. How should I structure the position parameter in the REST request?	fail→pass	22,003	5,332	-76%	1	1	0%	3,903	5,178	+33%	0	0	—
case-05 I need to create a new secondary table within an existing Notion database 'db_456' using HTTP POST. What endpoint and parent structure should be used?	fail→pass	10,272	4,816	-53%	1	1	0%	1,944	5,145	+165%	0	0	—
case-06 Can I use the Notion API comments endpoint to start a brand-new inline discussion thread highlighting text inside a paragraph block?	pass→pass	10,620	2,816	-73%	1	1	0%	1,792	4,608	+157%	0	0	—
case-07 My database page has a relation property referencing 40 different pages. When I fetch the page object via GET /v1/pages/{page_id}, why don't I see the full list of relation IDs directly in the page properties object?	pass→pass	8,318	5,982	-28%	1	1	0%	1,401	5,175	+269%	0	0	—
case-08 I am preparing a script to push 1,500 block elements in a single HTTP request body to Notion. What is the maximum number of block elements allowed per request payload?	fail→pass	7,800	4,705	-40%	1	1	0%	1,322	4,939	+274%	0	0	—
case-09 What curl call can my integration script execute to inspect its own bot user identity and permissions in Notion?	pass→pass	8,820	4,267	-52%	1	1	0%	1,576	4,868	+209%	0	0	—
case-10 To remove block 'blk_112233' in Notion, should I send a PATCH payload with archived set to true to /v1/blocks, or use a different endpoint?	pass→pass	6,864	4,740	-31%	1	1	0%	1,228	5,041	+311%	0	0	—
case-11 I have a CSV file with 50 customer profiles and want to batch generate 50 Notion pages under parent page 'pg_parent_100'. Provide the execution steps.	fail→pass	13,911	15,057	+8%	1	1	0%	2,399	7,146	+198%	0	0	—
case-12 How can I construct a POST search request in Notion to filter specifically for data sources rather than generic pages?	fail→pass	8,943	4,364	-51%	1	1	0%	1,789	4,951	+177%	0	0	—
case-13 When creating a new database in Notion via the API, what field inside parent must be provided to anchor it to a parent page?	pass→pass	4,079	3,233	-21%	1	1	0%	648	4,700	+625%	0	0	—
case-14 When retrieving page children blocks from GET /v1/blocks/{block_id}/children, what property in the response payload contains the string token to pass as start_cursor in the next fetch?	pass→pass	3,711	2,832	-24%	1	1	0%	572	4,649	+713%	0	0	—
case-15 If my Notion integration receives an HTTP 429 status code response, which response header should I inspect to know how long to pause before retrying?	pass→pass	2,835	1,983	-30%	1	1	0%	410	4,398	+973%	0	0	—
case-16 Construct a POST call to create a top-level page comment on page 'pg_778899' with text 'Review complete'.	pass→pass	6,883	5,795	-16%	1	1	0%	1,419	5,259	+271%	0	0	—
case-17 What is the recommended maximum schema size limit in kilobytes for Notion databases to ensure optimal performance?	fail→pass	9,762	1,586	-84%	1	1	0%	1,452	4,306	+197%	0	0	—
case-18 I want to insert a single paragraph block containing a continuous string of 3,500 characters in Notion. Will this payload be accepted?	pass→pass	9,270	5,280	-43%	1	1	0%	1,665	5,055	+204%	0	0	—
case-19 When fetching block children with GET /v1/blocks/{block_id}/children, how do I detect if an individual returned block contains nested child blocks under it?	pass→pass	8,862	4,378	-51%	1	1	0%	1,671	4,907	+194%	0	0	—
case-20 Which HTTP status code and error code does Notion return when a request times out after 60 seconds or when the platform is temporarily unavailable?	pass→pass	6,568	2,001	-70%	1	1	0%	1,167	4,406	+278%	0	0	—
case-21 How do I write a Notion Formula 2.0 expression that formats a date property 'Due' into 'YYYY-MM-DD' and checks if it is before today?	pass→pass	10,041	6,863	-32%	1	1	0%	1,730	5,222	+202%	0	0	—
case-22 Where in the Notion web settings UI do I navigate to generate a new internal integration secret token for my workspace?	pass→pass	6,326	6,545	+3%	1	1	0%	1,108	5,173	+367%	0	0	—
case-23 How do I configure Notion native REST webhooks to receive an HTTP POST callback on my server whenever any page property changes?	fail→pass	15,615	10,100	-35%	1	1	0%	2,670	5,772	+116%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 23 cases were attempted. The headline lift of +43 percentage points is the difference between those two pass rates over the 23 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 56.5%
Pass rate with the skill: 100%
Cases attempted: 23
Cases counted toward lift: 23
Cases that regressed: 0
Skill version measured: v1
Run completed: 8/21/2026, 22:40 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-01

Prompt

Look up any accessible workspace pages containing 'Q3 Roadmap' in Notion using a terminal curl command. Provide the API request snippet formatted to pipe into jq.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run100

Live evalNeeds ≥20 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+287% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 7 days ago

Other measured skills in the registry, with their headline benchmark lift.