{"id":"d8a52572-a0ed-4967-a2dc-3eac91b47954","shortId":"RYLHvB","kind":"skill","title":"notion","tagline":"Search, read, append to, and create Notion pages and databases via the Notion REST API. Use when the user mentions Notion, a page in their workspace, or wants to log something to a database.","description":"We drive the [Notion API](https://developers.notion.com/reference) with\n`curl + jq`. The user's OAuth bearer token is in `$NOTION_TOKEN`; every\ncall needs it plus the `Notion-Version` header.\n\nNotion-Version is currently `2022-06-28` (the most recent stable). Bump\nthis header when Notion ships a new version.\n\nThe user's connection only sees the pages and databases they explicitly\nshared with the integration when they authorized. If a search or page\nread returns nothing, the most likely cause is \"the page was never\nshared with the integration\" — surface that hint to the user.\n\n## Recipes\n\n### Verify auth (always run first)\n\n```sh\ncurl -sS https://api.notion.com/v1/users/me \\\n  -H \"Authorization: Bearer $NOTION_TOKEN\" \\\n  -H \"Notion-Version: 2022-06-28\" \\\n  | jq '{id, name, type, bot: (.bot != null)}'\n```\n\n### Search the workspace\n\n```sh\ncurl -sS https://api.notion.com/v1/search \\\n  -H \"Authorization: Bearer $NOTION_TOKEN\" \\\n  -H \"Notion-Version: 2022-06-28\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"Q1 budget\", \"page_size\": 10}' \\\n  | jq '.results[] | {id, type: .object, url, title: (.properties.title // .properties.Name)?.title?[0]?.plain_text // .child_page?.title}'\n```\n\n### Read a page (metadata only)\n\n```sh\ncurl -sS \"https://api.notion.com/v1/pages/PAGE_ID\" \\\n  -H \"Authorization: Bearer $NOTION_TOKEN\" \\\n  -H \"Notion-Version: 2022-06-28\"\n```\n\n### Read a page's full content\n\n```sh\ncurl -sS \"https://api.notion.com/v1/blocks/PAGE_ID/children?page_size=100\" \\\n  -H \"Authorization: Bearer $NOTION_TOKEN\" \\\n  -H \"Notion-Version: 2022-06-28\" \\\n  | jq '.results[] | {type, content: (.[.type] // {})}'\n```\n\n### Append a paragraph to a page\n\n```sh\ncurl -sS -X PATCH \"https://api.notion.com/v1/blocks/PAGE_ID/children\" \\\n  -H \"Authorization: Bearer $NOTION_TOKEN\" \\\n  -H \"Notion-Version: 2022-06-28\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"$(jq -nc --arg text \"Appended via the assistant.\" '\n    {children: [{\n      object: \"block\",\n      type: \"paragraph\",\n      paragraph: {rich_text: [{type:\"text\", text:{content:$text}}]}\n    }]}')\"\n```\n\n### Query a database\n\n```sh\ncurl -sS -X POST \"https://api.notion.com/v1/databases/DATABASE_ID/query\" \\\n  -H \"Authorization: Bearer $NOTION_TOKEN\" \\\n  -H \"Notion-Version: 2022-06-28\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"filter\": {\"property\": \"Status\", \"select\": {\"equals\": \"Open\"}},\n    \"sorts\":  [{\"property\": \"Updated\", \"direction\": \"descending\"}],\n    \"page_size\": 25\n  }'\n```\n\n### Create a page in a database\n\n```sh\ncurl -sS -X POST \"https://api.notion.com/v1/pages\" \\\n  -H \"Authorization: Bearer $NOTION_TOKEN\" \\\n  -H \"Notion-Version: 2022-06-28\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"$(jq -nc \\\n        --arg db \"DATABASE_ID\" \\\n        --arg title \"New entry\" \\\n        '{\n          parent: {database_id: $db},\n          properties: {\n            Name:   {title: [{text: {content: $title}}]},\n            Status: {select: {name: \"Open\"}}\n          }\n        }')\"\n```\n\n## Notes\n\n- Notion's pagination is cursor-based: append `start_cursor=$cursor` to\n  paginate, using the `next_cursor` from each response. Stop when\n  `has_more` is `false`.\n- Most write failures (400/404) come from a property type mismatch —\n  e.g. sending `{\"select\": \"Open\"}` instead of `{\"select\": {\"name\": \"Open\"}}`.\n  Read the database schema once via `GET /v1/databases/<id>` if unsure.","tags":["notion","skills","acedatacloud","acedata-cloud","agent-skills","agentskills","ai-image","ai-music","ai-tools","ai-video","claude-code","cursor"],"capabilities":["skill","source-acedatacloud","skill-notion","topic-acedata-cloud","topic-agent-skills","topic-agentskills","topic-ai-image","topic-ai-music","topic-ai-tools","topic-ai-video","topic-claude-code","topic-cursor","topic-gemini-cli","topic-github-copilot","topic-mcp"],"categories":["Skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/AceDataCloud/Skills/notion","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add AceDataCloud/Skills","source_repo":"https://github.com/AceDataCloud/Skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (3,374 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:14:03.357Z","embedding":null,"createdAt":"2026-05-18T13:21:34.168Z","updatedAt":"2026-05-18T19:14:03.357Z","lastSeenAt":"2026-05-18T19:14:03.357Z","tsv":"'-06':73,156,184,235,259,290,340,386 '-28':74,157,185,236,260,291,341,387 '/reference)':43 '/v1/blocks/page_id/children':279 '/v1/blocks/page_id/children?page_size=100':248 '/v1/databases':471 '/v1/databases/database_id/query':329 '/v1/pages':375 '/v1/pages/page_id':224 '/v1/search':173 '/v1/users/me':145 '0':208 '10':197 '2022':72,155,183,234,258,289,339,385 '25':361 '400/404':448 'alway':137 'api':16,40 'api.notion.com':144,172,223,247,278,328,374 'api.notion.com/v1/blocks/page_id/children':277 'api.notion.com/v1/blocks/page_id/children?page_size=100':246 'api.notion.com/v1/databases/database_id/query':327 'api.notion.com/v1/pages':373 'api.notion.com/v1/pages/page_id':222 'api.notion.com/v1/search':171 'api.notion.com/v1/users/me':143 'append':4,266,302,426 'application/json':190,296,346,392 'arg':300,396,400 'assist':305 'auth':136 'author':106,147,175,226,250,281,331,377 'base':425 'bearer':51,148,176,227,251,282,332,378 'block':308 'bot':162,163 'budget':194 'bump':79 'call':58 'caus':118 'child':211 'children':306 'come':449 'connect':91 'content':188,242,264,294,317,344,390,412 'content-typ':187,293,343,389 'creat':7,362 'curl':45,141,169,220,244,273,323,369 'current':71 'cursor':424,428,429,435 'cursor-bas':423 'd':191,297,347,393 'databas':11,35,97,321,367,398,405,466 'db':397,407 'descend':358 'developers.notion.com':42 'developers.notion.com/reference)':41 'direct':357 'drive':37 'e.g':455 'entri':403 'equal':352 'everi':57 'explicit':99 'failur':447 'fals':444 'filter':348 'first':139 'full':241 'get':470 'h':146,151,174,179,186,225,230,249,254,280,285,292,330,335,342,376,381,388 'header':66,81 'hint':130 'id':159,200,399,406 'instead':459 'integr':103,127 'jq':46,158,198,261,298,394 'like':117 'log':31 'mention':21 'metadata':217 'mismatch':454 'name':160,409,416,462 'nc':299,395 'need':59 'never':123 'new':86,402 'next':434 'note':418 'noth':114 'notion':1,8,14,22,39,55,64,68,83,149,153,177,181,228,232,252,256,283,287,333,337,379,383,419 'notion-vers':63,67,152,180,231,255,286,336,382 'null':164 'oauth':50 'object':202,307 'open':353,417,458,463 'page':9,24,95,111,121,195,212,216,239,271,359,364 'pagin':421,431 'paragraph':268,310,311 'parent':404 'patch':276 'plain':209 'plus':61 'post':326,372 'properti':349,355,408,452 'properties.name':206 'properties.title':205 'q1':193 'queri':192,319 'read':3,112,214,237,464 'recent':77 'recip':134 'respons':438 'rest':15 'result':199,262 'return':113 'rich':312 'run':138 'schema':467 'search':2,109,165 'see':93 'select':351,415,457,461 'send':456 'sh':140,168,219,243,272,322,368 'share':100,124 'ship':84 'size':196,360 'skill' 'skill-notion' 'someth':32 'sort':354 'source-acedatacloud' 'ss':142,170,221,245,274,324,370 'stabl':78 'start':427 'status':350,414 'stop':439 'surfac':128 'text':210,301,313,315,316,318,411 'titl':204,207,213,401,410,413 'token':52,56,150,178,229,253,284,334,380 'topic-acedata-cloud' 'topic-agent-skills' 'topic-agentskills' 'topic-ai-image' 'topic-ai-music' 'topic-ai-tools' 'topic-ai-video' 'topic-claude-code' 'topic-cursor' 'topic-gemini-cli' 'topic-github-copilot' 'topic-mcp' 'type':161,189,201,263,265,295,309,314,345,391,453 'unsur':473 'updat':356 'url':203 'use':17,432 'user':20,48,89,133 'verifi':135 'version':65,69,87,154,182,233,257,288,338,384 'via':12,303,469 'want':29 'workspac':27,167 'write':446 'x':275,325,371","prices":[{"id":"1928ade5-c8cb-4693-8485-579630d1adf4","listingId":"d8a52572-a0ed-4967-a2dc-3eac91b47954","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"AceDataCloud","category":"Skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:34.168Z"}],"sources":[{"listingId":"d8a52572-a0ed-4967-a2dc-3eac91b47954","source":"github","sourceId":"AceDataCloud/Skills/notion","sourceUrl":"https://github.com/AceDataCloud/Skills/tree/main/skills/notion","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:34.168Z","lastSeenAt":"2026-05-18T19:14:03.357Z"}],"details":{"listingId":"d8a52572-a0ed-4967-a2dc-3eac91b47954","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"AceDataCloud","slug":"notion","github":{"repo":"AceDataCloud/Skills","stars":7,"topics":["acedata-cloud","agent-skills","agentskills","ai-image","ai-music","ai-tools","ai-video","claude-code","cursor","gemini-cli","github-copilot","mcp","npm","openai-codex","roo-code"],"license":"other","html_url":"https://github.com/AceDataCloud/Skills","pushed_at":"2026-05-18T07:35:03Z","description":"Agent Skills for AceDataCloud AI services — music, image, video generation, web search, and more. Compatible with Claude Code, GitHub Copilot, Gemini CLI, and all agentskills.io-compatible agents.","skill_md_sha":"12fc0f5ddcd7fe21acd32dcbf448da96afeb9dcc","skill_md_path":"skills/notion/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/AceDataCloud/Skills/tree/main/skills/notion"},"layout":"multi","source":"github","category":"Skills","frontmatter":{"name":"notion","license":"Apache-2.0","description":"Search, read, append to, and create Notion pages and databases via the Notion REST API. Use when the user mentions Notion, a page in their workspace, or wants to log something to a database."},"skills_sh_url":"https://skills.sh/AceDataCloud/Skills/notion"},"updatedAt":"2026-05-18T19:14:03.357Z"}}