@kody/notion

@kody/notion

Notion logo

Intent

Provide reusable, account-agnostic Notion helpers that let Kody search, read, and query the pages and databases shared with the connected Notion integration, and make explicitly confirmed writes, with a generic escape hatch for the rest of the Notion API.

Required setup

Create a Notion public integration and save a Kody OAuth integration named notion.

1. Create an integration at https://www.notion.so/profile/integrations and set its type to Public.
2. Set the redirect URI to https://heykody.dev/connect/oauth.
3. Save the integration in Kody with:
   • Authorize URL: https://api.notion.com/v1/oauth/authorize
   • Token URL: https://api.notion.com/v1/oauth/token
   • API base: https://api.notion.com/v1
   • API host: api.notion.com
   • Flow: confidential (token exchange uses Basic auth with a JSON body)
   • Extra authorize params: owner=user, response_type=code
   • Scopes: none (access is granted per page during the OAuth consent screen)
4. Connect or reconnect at https://heykody.dev/connect/oauth?provider=notion.

During the OAuth flow, Notion asks which pages to share with the integration. Helpers can only see pages and databases the authorizing user shared.

Exports

• kody:@kody/notion — package overview and safety metadata
• kody:@kody/notion/smoke-test — verify OAuth access without returning workspace or user PII
• kody:@kody/notion/request — generic authenticated Notion API request; mutating calls require confirm: true
• kody:@kody/notion/search — search shared pages and data sources (objectType: 'page' | 'data_source')
• kody:@kody/notion/get-page — read a page's metadata and properties
• kody:@kody/notion/get-block-children — read a page or block's content blocks
• kody:@kody/notion/get-database — read a database container: title and its data sources
• kody:@kody/notion/get-data-source — read a data source's schema/properties by data source id
• kody:@kody/notion/query-database — query rows; accepts dataSourceId or databaseId (auto-resolves the single data source)
• kody:@kody/notion/create-page — preview or create a page; creating requires confirm: true; parent.database_id auto-resolves to the data source
• kody:@kody/notion/append-block-children — preview or append blocks; appending requires confirm: true; position via position: { type: 'after_block' | 'start' | 'end' }

Examples

import search from 'kody:@kody/notion/search'

export default async function main() {
  return search({ query: 'meeting notes', objectType: 'page' })
}

import createPage from 'kody:@kody/notion/create-page'

export default async function main() {
  return createPage({
    // database_id auto-resolves to the database's single data source
    parent: { database_id: '00000000-0000-0000-0000-000000000000' },
    properties: {
      Name: { title: [{ text: { content: 'New page' } }] },
    },
    dryRun: true,
  })
}

Set confirm: true only after the user has explicitly approved the exact destination and content. A dry run never calls Notion.

API model (Notion-Version 2026-03-11)

All helpers pin Notion-Version 2026-03-11 (request accepts a notionVersion param to override for one-off calls). The modern model:

• Databases are containers; data sources hold the schema and rows. get-database returns the container's data_sources list; get-data-source returns properties; rows are queried via POST /data_sources/{id}/query. Helpers that take databaseId auto-resolve the database's single data source and error if there are several.
• Database-row pages need a data source parent (parent: { data_source_id }). create-page auto-converts parent.database_id for you.
• Search returns data_source objects where databases used to appear; filter with objectType: 'page' | 'data_source'.
• Block positioning uses position: { type: 'after_block', after_block: { id } } (or start / end) — the flat after parameter is gone.
• Trash is in_trash — the archived field no longer exists in requests or responses.
• To create an inline child database on a page (e.g. a per-page gallery), use request with POST /databases, parent: { type: 'page_id', page_id }, is_inline: true, and the schema under initial_data_source: { properties }. There is no way to create a child_database block through append-block-children.
• Notion rewrites prop("Name") formula expressions into internal block-property references on save; don't round-trip a saved formula expression back into a create/update payload — keep the human-readable form in your source of truth.

Pagination

List-style helpers accept pageSize (1–100) and startCursor, and return hasMore plus nextCursor for fetching the next page.