Notion Api
Look up correct Notion API block JSON shapes when your agent builds or updates pages, databases, and nested block trees.
Overview
Notion API is an agent skill for the Build phase that documents Notion REST block types and JSON payloads for correct page and content integration.
Install
npx skills add https://github.com/intellectronica/agent-skills --skill notion-apiWhat is this skill?
- Documents the common block envelope (object, id, type, parent, timestamps, archived flags)
- Covers text blocks: paragraph, heading_1/2/3 (toggleable), quote, and callout with rich_text and color
- Explains when blocks support children for nested page content
- JSON examples per block type for copy-paste agent payloads
- Reference-oriented layout for fast lookup during API implementation
Adoption & trust: 37k installs on skills.sh; 270 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are calling the Notion API but block payloads fail validation because type-specific fields and nesting rules are easy to misremember.
Who is it for?
Solo builders syncing specs, tasks, or knowledge bases to Notion from code or agent workflows.
Skip if: Teams that only need Notion UI editing with no API automation, or work that is pure in-app logic unrelated to Notion.
When should I use this skill?
When implementing or fixing Notion API block create/update calls and you need authoritative JSON shapes for supported text block types.
What do I get? / Deliverables
Your agent emits structurally valid Notion blocks with the right rich_text and parent references so create-and-append operations succeed reliably.
- Valid Notion block JSON snippets aligned to documented types
- Nested block trees where headings or containers allow children
Recommended Skills
Journey fit
Notion API block reference is used while wiring product or agent workflows to Notion, which is core integration work in Build. Integrations subphase is where third-party APIs like Notion are modeled, validated, and called from app or agent code.
How it compares
A block-schema reference skill, not a hosted MCP server or OAuth setup wizard.
Common Questions / FAQ
Who is notion-api for?
Indie developers and agent users who integrate Notion pages and databases programmatically and need accurate block JSON without re-reading the full API docs each time.
When should I use notion-api?
During Build integrations when creating paragraphs, headings, quotes, callouts, or nested children; when debugging malformed block bodies; or when scaffolding agents that publish documentation into Notion.
Is notion-api safe to install?
Review the Security Audits panel on this Prism page and the skill source in the linked repo before granting network or secret access to your Notion integration token.
SKILL.md
READMESKILL.md - Notion Api
# Notion Block Types Reference This document provides comprehensive documentation for all supported block types in the Notion API. ## Block Structure Every block contains these common fields: ```json { "object": "block", "id": "uuid", "type": "block_type", "parent": {"type": "page_id", "page_id": "..."}, "created_time": "2024-01-01T00:00:00.000Z", "last_edited_time": "2024-01-01T00:00:00.000Z", "created_by": {"object": "user", "id": "..."}, "last_edited_by": {"object": "user", "id": "..."}, "archived": false, "in_trash": false, "has_children": false, "{type}": { /* type-specific properties */ } } ``` ## Text Blocks ### Paragraph ```json { "type": "paragraph", "paragraph": { "rich_text": [{"type": "text", "text": {"content": "Paragraph text"}}], "color": "default" } } ``` Supports children (nested blocks). ### Headings ```json { "type": "heading_1", "heading_1": { "rich_text": [{"type": "text", "text": {"content": "Heading 1"}}], "color": "default", "is_toggleable": false } } ``` Types: `heading_1`, `heading_2`, `heading_3` When `is_toggleable: true`, headings can contain children. ### Quote ```json { "type": "quote", "quote": { "rich_text": [{"type": "text", "text": {"content": "Quote text"}}], "color": "default" } } ``` Supports children. ### Callout ```json { "type": "callout", "callout": { "rich_text": [{"type": "text", "text": {"content": "Callout text"}}], "icon": {"type": "emoji", "emoji": "💡"}, "color": "gray_background" } } ``` Supports children. Icon can be emoji or file. ### Code ```json { "type": "code", "code": { "rich_text": [{"type": "text", "text": {"content": "const x = 1;"}}], "caption": [], "language": "javascript" } } ``` Supported languages: `abap`, `arduino`, `bash`, `basic`, `c`, `clojure`, `coffeescript`, `cpp`, `csharp`, `css`, `dart`, `diff`, `docker`, `elixir`, `elm`, `erlang`, `flow`, `fortran`, `fsharp`, `gherkin`, `glsl`, `go`, `graphql`, `groovy`, `haskell`, `html`, `java`, `javascript`, `json`, `julia`, `kotlin`, `latex`, `less`, `lisp`, `livescript`, `lua`, `makefile`, `markdown`, `markup`, `matlab`, `mermaid`, `nix`, `objective-c`, `ocaml`, `pascal`, `perl`, `php`, `plain text`, `powershell`, `prolog`, `protobuf`, `python`, `r`, `reason`, `ruby`, `rust`, `sass`, `scala`, `scheme`, `scss`, `shell`, `sql`, `swift`, `typescript`, `vb.net`, `verilog`, `vhdl`, `visual basic`, `webassembly`, `xml`, `yaml`, `java/c/c++/c#` ### Equation ```json { "type": "equation", "equation": { "expression": "E = mc^2" } } ``` Uses LaTeX/KaTeX syntax. ## List Blocks ### Bulleted List Item ```json { "type": "bulleted_list_item", "bulleted_list_item": { "rich_text": [{"type": "text", "text": {"content": "List item"}}], "color": "default" } } ``` Supports children (nested list items). ### Numbered List Item ```json { "type": "numbered_list_item", "numbered_list_item": { "rich_text": [{"type": "text", "text": {"content": "List item"}}], "color": "default" } } ``` Supports children. ### To-Do ```json { "type": "to_do", "to_do": { "rich_text": [{"type": "text", "text": {"content": "Task"}}], "checked": false, "color": "default" } } ``` Supports children. ### Toggle ```json { "type": "toggle", "toggle": { "rich_text": [{"type": "text", "text": {"content": "Toggle header"}}], "color": "default" } } ``` Supports children (the toggle content). ## Media Blocks ### Image ```json { "type": "image", "image": { "type": "external", "external": {"url": "https://example.com/image.png"}, "caption": [] } } ``` Or for uploaded files: ```json { "type": "image", "image": { "type": "file", "file": {"url": "https://...", "expiry_time": "..."}, "caption": [] } } ``` Supported formats: `.bmp`, `.gif`, `.heic`, `.jpeg`, `.jpg`, `.png`, `.svg`, `.tif`, `.tiff` ### Video ```json { "type": "v