Work with Notion Pages and Databases in Hermes
The bundled Notion skill supports two routes: the ntn CLI on macOS or Linux when available, and direct HTTPS requests as a cross-platform fallback. Both require a Notion integration token and access to the pages or data sources the integration must use.
Official skill reference: Notion
Select a path deliberately
Use ntn for concise search, Markdown page operations, file uploads, and worker tooling. Use the HTTP API when the CLI is unavailable or when a transparent cross-platform request is preferable. Keep the current Notion API version from the official skill reference; database concepts and data-source endpoints can differ across versions.
Start with search and page metadata. Read a page through the Markdown endpoint for agent-friendly editing, or read block children when exact structure matters. For data collections, inspect the parent, properties, and data-source identifier before querying or creating rows.
Notion change checklist
- Share the target page or data source with the integration.
- Keep the integration token in environment or secret storage.
- Search and read before creating a similar page.
- Choose Markdown operations for prose and typed properties for database rows.
- Preserve property types, relation targets, and select values.
- Re-fetch the page or row after every mutation.
Common pitfalls
- Assuming a visible page is integration-accessible. Notion access must be granted to the integration.
- Mixing database and data-source identifiers. Use the endpoint and identifier required by the current API version.
- Replacing a page when an append or patch was intended. Read current content and define the edit boundary.
- Embedding raw tokens in examples or shell history. Use protected environment values and redact outputs.
- Reporting an upload before attachment. Upload creation, byte transfer, and page reference are separate stages on the HTTP path.
Verification
Read the page as Markdown and, when structure matters, inspect its blocks. For a data-source mutation, query the specific row and compare typed properties. For uploads, verify the page references the completed file and that an authorized user can open it. A successful status code without a read-back is not a finished workflow.