Use the Notion CLI from KosmoKrator to call Notion tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.
Notion can be configured headlessly with `kosmokrator integrations:configure notion`.
# Install KosmoKrator first if it is not available on PATH.curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash# Configure and verify this integration.kosmokrator integrations:configure notion --set api_key="$NOTION_API_KEY" --enable --read allow --write ask --jsonkosmokrator integrations:doctor notion --jsonkosmokrator integrations:status --json
Credentials
Authentication type: API keyapi_key. Configure credentials once, then use the same stored profile from
scripts, coding CLIs, Lua code mode, and the MCP gateway.
Key
Env var
Type
Required
Label
api_key
NOTION_API_KEY
Secret secret
yes
API Key
Call Notion Headlessly
Use the generic call form when another coding CLI or script needs a stable universal interface.
Every function below can be called headlessly. The generic form is stable across all integrations;
the provider shortcut is shorter but specific to Notion.
notion.notion_search
Read read
Search pages and databases in your Notion workspace.
Returns matching results with their IDs, types, and titles.
Optionally filter by type (page or database) and control sort direction.
Create a new page in Notion. The page can be created as a child of a database
(to create a row) or as a child of another page (to create a sub-page).
Provide properties as a JSON object matching the database schema when using a database parent.
Provide children (block content) as a JSON array of block objects.
Create a new database as a child of a page. Provide the parent page ID,
a title, and a properties schema. Properties define the columns of the database.
Example properties: {"Name": {"title": {}}, "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}}}.
Query a Notion database to retrieve rows (pages). Supports filtering and sorting.
Filter and sorts can be provided as JSON strings or arrays.
Example filter: {"property": "Status", "select": {"equals": "Done"}}
Example sorts: [{"property": "Name", "direction": "ascending"}]
Get the child blocks of a Notion block or page. Returns a list of block objects.
Use this to read the content of a page or to navigate nested block structures.
Supports pagination.
Append blocks to a Notion page or block. Provide children as a JSON array of block objects.
Example: [{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello world"}}]}}]
Update the content of a Notion block. Provide the block ID and the type-specific
content to update. For example, to update a paragraph block, provide:
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "New text"}}]}}
Only the fields you include will be updated.
Create a comment on a Notion page. You can either start a new discussion
(provide parent_id) or reply to an existing discussion (provide discussion_id).
Provide body_text for simple text, or body_children for rich content blocks.
Use these parameter tables when building CLI payloads without calling integrations:schema first.
notion.notion_search
Search pages and databases in your Notion workspace.
Returns matching results with their IDs, types, and titles.
Optionally filter by type (page or database) and control sort direction.
Sort direction: "ascending" or "descending". Defaults to descending (last edited first).
page_size
integer
no
Number of results per page (max 100, default 10).
start_cursor
string
no
Pagination cursor from a previous response.
notion.notion_create_page
Create a new page in Notion. The page can be created as a child of a database
(to create a row) or as a child of another page (to create a sub-page).
Provide properties as a JSON object matching the database schema when using a database parent.
Provide children (block content) as a JSON array of block objects.
Create a new database as a child of a page. Provide the parent page ID,
a title, and a properties schema. Properties define the columns of the database.
Example properties: {"Name": {"title": {}}, "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}}}.
Updated property schema as a JSON object. Only included properties will be updated.
notion.notion_query_database
Query a Notion database to retrieve rows (pages). Supports filtering and sorting.
Filter and sorts can be provided as JSON strings or arrays.
Example filter: {"property": "Status", "select": {"equals": "Done"}}
Example sorts: [{"property": "Name", "direction": "ascending"}]
Get the child blocks of a Notion block or page. Returns a list of block objects.
Use this to read the content of a page or to navigate nested block structures.
Supports pagination.
Number of results per page (max 100, default 100).
start_cursor
string
no
Pagination cursor from a previous response.
notion.notion_append_block_children
Append blocks to a Notion page or block. Provide children as a JSON array of block objects.
Example: [{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello world"}}]}}]
Update the content of a Notion block. Provide the block ID and the type-specific
content to update. For example, to update a paragraph block, provide:
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "New text"}}]}}
Only the fields you include will be updated.
Create a comment on a Notion page. You can either start a new discussion
(provide parent_id) or reply to an existing discussion (provide discussion_id).
Provide body_text for simple text, or body_children for rich content blocks.
Number of results per page (max 100, default 100).
start_cursor
string
no
Pagination cursor from a previous response.
Permissions
Headless calls still follow the integration read/write permission policy. Configure read/write defaults
with integrations:configure. Add --force only for trusted automation that should bypass that policy.
