> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Notion

> A stateful replica of the Notion API: pages, blocks, databases and data sources, comments, users and search, as an internal integration sees them.

The Notion replica implements 19 endpoints of the Notion API, version `2025-09-03`, for an internal integration: it sees only the pages shared with it, as Notion does. Its key is `notion`. It was tested with `@notionhq/client`.

## Connect

| Variable | Value |
| - | - |
| `NOTION_API_URL` | Base URL. Paths start with `/v1/`. |
| `NOTION_TOKEN` | Fake internal integration token. Send `Authorization: Bearer <token>`. |

```js Node theme={null}
import { Client } from '@notionhq/client';
const notion = new Client({ auth: process.env.NOTION_TOKEN, baseUrl: process.env.NOTION_API_URL });
const { results } = await notion.search({ query: 'runbook' });
```

This is what `ancha connect notion --lang ts` prints. Send `Notion-Version: 2025-09-03`, as the current client does; requests with an older version are coverage gaps, because databases are served as data sources.

## Endpoints

| Method | Path | Support |
| - | - | - |
| `GET` | `/v1/users/me`, `/v1/users`, `/v1/users/:user_id` | supported |
| `POST` | `/v1/search` | partial: matches titles; filter by object (`page` or `data_source`); sorted by `last_edited_time` |
| `POST` | `/v1/pages` | partial: parents `page_id`, `data_source_id` or `database_id`; emoji icons; covers, templates and markdown content are gaps |
| `GET` | `/v1/pages/:page_id` | supported |
| `PATCH` | `/v1/pages/:page_id` | partial: properties, trash and emoji icons; locking, covers and templates are gaps |
| `GET` | `/v1/pages/:page_id/properties/:property_id` | supported |
| `GET` | `/v1/blocks/:block_id` | supported |
| `PATCH` | `/v1/blocks/:block_id` | partial: text, checked state, language and trash for the supported block types |
| `DELETE` | `/v1/blocks/:block_id` | supported: moves the block, or child page, to the trash |
| `GET` | `/v1/blocks/:block_id/children` | supported: child pages and databases appear as `child_page` and `child_database` blocks |
| `PATCH` | `/v1/blocks/:block_id/children` | partial: appends at the end or after a sibling; paragraph, headings, lists, to-dos, toggles, quotes, callouts, code, dividers and bookmarks; other block types are gaps |
| `GET` | `/v1/databases/:database_id` | supported |
| `GET` | `/v1/data_sources/:data_source_id` | supported |
| `POST` | `/v1/data_sources/:data_source_id/query` | partial: property filters for text, number, checkbox, select, status, multi-select, people and date, timestamp filters, `and`/`or`, sorts |
| `POST` | `/v1/comments` | partial: comments on pages and replies to discussions; attachments and markdown are gaps |
| `GET` | `/v1/comments`, `/v1/comments/:comment_id` | supported |

Anything else returns HTTP 501 with Notion's error shape and `x-ancha-gap: 1`.

## Starter data

The `notion-starter` dataset is the workspace **Acme**, with the integration **Ancha** and eight users: Ben Carter, Ellen Price, Greg Wilson, Rachel Moore, Laura Kim, Mike Turner, Tom Hughes and Victor Lane.

| Page | Contents |
| - | - |
| Engineering | A top-level page shared with the integration, with two children: "Orders API runbook" (headings, a numbered list, a callout about rolling back 4.12.1 and a bookmark) and "On-call handbook". |
| Product | A top-level page with "Scheduled reports spec" (requirements as to-dos, open questions, and two comments) and "Roadmap review: Thursday", plus two databases. |
| Leadership | Not shared with the integration. Its child "Board deck draft" is shared. |

| Database | Properties | Rows |
| - | - | - |
| Customer feedback | Feedback (title), Customer (select), Theme (multi-select), Status, Votes (number), Owner (people), Received (date), Link (URL) | Six requests: weekly scheduled reports (Pinecrest Health, in progress, 12 votes), SCIM provisioning with Okta (Bluefield Logistics), exports that take minutes to appear (Ridgeway Robotics), daily totals counted twice (Kestrel Credit Union, done), dark mode (Summit Freight) and a usage report for a renewal review (Helix Manufacturing). |
| Meeting notes | Name (title), Date, Type (select), Attendees (people) | Three: the Ridgeway Robotics pilot kickoff, the Helix Manufacturing quarterly review prep, and the 4.12.1 rollback retro with two open to-dos. |

`ancha sandbox configuration --tools notion --json` prints every block and row.

## Checks

Notion has no state checks. Use trace checks, for example `{ called: "POST /v1/pages" }` or `{ not_called: "DELETE /v1/blocks/*" }`.

## Limits

* An internal integration: it sees only pages shared with it, as Notion does.
* Text, heading, list, to-do, toggle, quote, callout, code, divider and bookmark blocks; images, files, tables, synced blocks, relations, rollups, formulas and markdown endpoints are gaps.
* Requests with a `Notion-Version` before `2025-09-03` are coverage gaps: databases are served as data sources.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [Introduction](https://docs.ancha.io/index.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.