> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt
> Use this file to discover all available pages before exploring further.
# Notion
> Read and write pages, blocks, databases and comments in a Notion workspace.
```python notion_example.py {7} theme={null}
from charter.auth import EnvTokenProvider
from charter.packs import notion
credentials = EnvTokenProvider("NOTION_API_KEY")
notion.configure(credentials)
page = await notion.pages_create.ainvoke(
body={
"parent": {"data_source_id": DATA_SOURCE_ID},
"properties": {"Name": {"title": [{"text": {"content": "Ship it"}}]}},
},
)
```
Notion is two APIs wearing one coat. There is a document API, where a page is a
tree of blocks, and a database API, where a page is a row and its properties are
columns. The same `pages_create` call does both, and which one you get depends
on the parent you give it.
## A database is not the table
Since Notion's `2025-09-03` version a database is a container and a **data
source** is the table inside it. The columns belong to the data source, rows are
queried from it, and a page created inside a database takes a `data_source_id`
as its parent.
That matters for the first call you make. `databases_retrieve` returns the data
sources a database holds; `data_sources_retrieve` returns the column schema you
have to write against. Querying rows or changing columns through a database ID
is the older shape, which still answers for a database with one table and fails
for one with several.
## Authenticating
This pack takes an OAuth bearer token, and [`configure()`](/charter/charter/reference/configuration#configure) is optional when `$NOTION_API_KEY` is set. Which credential provider you hand it depends on whose account the calls run as.
### A token you hold
For a script, or a notebook. [`EnvTokenProvider`](/charter/charter/reference/credentials#envtokenprovider) re-reads the variable on every call, so a token rotated beside the process is picked up without a restart; [`StaticTokenProvider`](/charter/charter/reference/credentials#statictokenprovider) takes one you already hold as a string. Neither renews anything, so the calls stop when the token expires.
```python notion_script.py {4} theme={null}
from charter.auth import EnvTokenProvider
from charter.packs import notion
credentials = EnvTokenProvider("NOTION_API_KEY")
notion.configure(credentials)
```
### One account, refreshed
For an agent or a server acting as you. [`OAuth2Client`](/charter/charter/reference/oauth#oauth2client) turns a client registration and a stored refresh token into an access token, and [renews it](/charter/charter/auth/authorization-servers#what-the-cache-does-precisely) before it lapses.
```python notion_agent.py {8} theme={null}
from charter.auth import OAuth2Client
from charter.packs import notion
credentials = OAuth2Client(
NOTION,
client_id=os.environ["NOTION_CLIENT_ID"],
client_secret=os.environ["NOTION_CLIENT_SECRET"],
refresh_token=os.environ["NOTION_REFRESH_TOKEN"],
)
notion.configure(credentials)
```
No refresh token yet? [Your own account](/charter/charter/auth/your-own-account) is the one-time consent flow that hands you one.
### Many end users
For a product whose users each connect their own account. [`SubjectProvider`](/charter/charter/reference/credentials#subjectprovider) builds one credential per user through a factory you write, and [`use_subject`](/charter/charter/reference/credentials#use_subject) names the user a call acts for. [Your users' accounts](/charter/charter/auth/oauth-flow) is the consent route inside your app; [serving many users](/charter/charter/auth/authorization-servers#serving-many-users) is the per-subject cache and its eviction.
```python notion_server.py {17,21} theme={null}
from functools import partial
from charter.auth import OAuth2Client, SubjectProvider, use_subject
from charter.packs import notion
# Yours to write: a user id in, that user's credential out.
async def for_user(user_id: str) -> OAuth2Client:
grant = await db.grants.get(user_id, "notion")
return OAuth2Client(
NOTION,
client_id=os.environ["NOTION_CLIENT_ID"],
client_secret=os.environ["NOTION_CLIENT_SECRET"],
refresh_token=grant.refresh_token,
on_refresh=partial(save_to_db, user_id),
)
credentials = SubjectProvider(for_user)
notion.configure(credentials)
# Per request: whose grant the tools use.
with use_subject(request.user_id):
... # your agent runs here
```
Connecting a workspace you do not own is an OAuth flow rather than a pasted
secret. [Using your own account](/charter/charter/auth/your-own-account) covers the single-token
case, which is what an internal integration is.
An internal integration secret is prefixed `ntn_` and goes out as a bearer
token. An OAuth access token works the same way, and so does a personal access
token, with one difference worth knowing: `users_list` refuses a personal access
token.
Notion's permissions are not scopes you request per call. An integration is
given capabilities in Notion's own settings, and each tool page names the one it
needs by the label you tick there. An integration also only sees pages somebody
has shared with it. A page that has not been shared is a 404, not a 403, so an empty
`search` usually means nothing has been shared rather than that nothing exists.
## The client
[`oauth_tool_factory`](/charter/charter/reference/factories#oauth_tool_factory) is the whole client: a thin wrapper over `httpx` that attaches your token and these endpoint constants to each request. No vendor SDK enters your dependency tree.
```python Without the pack theme={null}
from charter import oauth_tool_factory
notion_api_client = oauth_tool_factory(
base_url="https://api.notion.com/",
provider="notion",
credential_provider=credentials,
body_format="json",
query_format="repeat",
body_case="snake",
query_case="snake",
path_case="snake",
static_headers={"Notion-Version": "2026-03-11"},
# this API reports failure with an HTTP status code
envelope=None,
)
```
```python With the pack theme={null}
from charter.packs import notion
notion.configure(credentials)
# The base URL, the casing, the envelope and the pagination are
# already declared. 35 tools, ready to hand to a model:
tools = notion.TOOLS
```
`credentials` is whichever of the three you built in [Authenticating](#authenticating). A pack takes it through [`configure()`](/charter/charter/reference/configuration#configure); a client you build takes the same object as `credential_provider`, and has no `configure()` of its own.
### Paging through a list
A cursor belongs to the tool that returns it, so it is declared on that tool's builder call:
```python notion_pagination.py theme={null}
# On users_list, pages_retrieve_property_item,
# blocks_children_list, data_sources_templates_list,
# comments_list, file_uploads_list and custom_emojis_list.
users_list = notion_api_client(
name="users_list",
args_schema=UsersListRequest,
method="GET",
url_template="v1/users",
pagination=Pagination(
cursor_field="next_cursor",
cursor_param="start_cursor",
more_field="has_more",
),
)
# On search and data_sources_query.
search = notion_api_client(
name="search",
args_schema=SearchRequest,
method="POST",
url_template="v1/search",
pagination=Pagination(
cursor_field="next_cursor",
cursor_param="body.start_cursor",
more_field="has_more",
),
)
```
Pagination is declared on `users_list`, `pages_retrieve_property_item`, `blocks_children_list`, `data_sources_templates_list`, `comments_list`, `file_uploads_list`, `custom_emojis_list`, `search` and `data_sources_query`. The other 26 take no cursor.
`Notion-Version` is required on every request. Omit it and the answer is `400
missing_version`, so there is no unpinned mode to fall back to. The pack sends
`2026-03-11`, which is the version that renamed `archived` to `in_trash` and
replaced block append's `after` parameter with `position`.
## Tools
Each is a [`Tool`](/charter/charter/reference/tool), called with
[`ainvoke`](/charter/charter/reference/tool#tool-ainvoke) as in the snippet above. The name
links to its parameters, its response and what it costs.
Users
users\_listGET
List the people and bots in the workspace.
users\_retrieveGET
Get one user by ID.
users\_retrieve\_meGET
Get the bot this token authenticates as, including which workspace it is in.
Search
searchPOST
Search the titles of pages and data sources shared with this integration.
Pages
pages\_createPOST
Create a page — as a subpage of another page, or as a row of a database by giving its data\_source\_id as the parent.
pages\_retrieveGET
Get a page's properties.
pages\_updatePATCH
Update a page's property values, icon, cover, or trash state.
pages\_movePOST
Move a page under a different parent page or data source.
pages\_retrieve\_property\_itemGET
Read one property of a page in full.
pages\_retrieve\_markdownGET
Get a page's whole content as Markdown, rendered by Notion.
pages\_update\_markdownPATCH
Replace a page's content with Markdown, which Notion parses into blocks.
Blocks
blocks\_retrieveGET
Get one block.
blocks\_updatePATCH
Update a block's content, or trash and restore it with in\_trash.
blocks\_deleteDELETE
Move a block to the trash.
blocks\_children\_listGET
List the direct children of a block, or of a page when given a page ID.
blocks\_children\_appendPATCH
Append blocks to a page or a block.
Databases
databases\_createPOST
Create a database on a page or at the top of the workspace.
databases\_retrieveGET
Get a database and the data sources it contains.
databases\_updatePATCH
Update a database's title, description, icon, cover, inline display or trash state, or move it to a new parent.
Data sources
data\_sources\_createPOST
Add another table to an existing database.
data\_sources\_retrieveGET
Get a data source's column schema — the names, types and select options a write has to match.
data\_sources\_updatePATCH
Change a data source's columns, title or icon.
data\_sources\_queryPOST
Get the rows of a data source, optionally filtered and sorted.
data\_sources\_templates\_listGET
List the page templates defined on a data source.
Comments
comments\_createPOST
Comment on a page or block, or reply to an existing discussion with its discussion\_id.
comments\_listGET
List the unresolved comments on a page or block.
comments\_retrieveGET
Get one comment by ID.
comments\_updatePATCH
Edit a comment's content, replacing it entirely.
comments\_deleteDELETE
Delete a comment.
File uploads
file\_uploads\_createPOST
Start a file upload.
file\_uploads\_completePOST
Finish a multi-part upload once every part has been sent.
file\_uploads\_retrieveGET
Get a file upload and its status.
file\_uploads\_listGET
List this integration's file uploads, optionally by status.
Custom emojis
custom\_emojis\_listGET
List the workspace's own uploaded emoji.
Async tasks
async\_tasks\_retrieveGET
Check work Notion took in the background.
## Reading a page
There are three ways, and they cost very different amounts.
`pages_retrieve` returns the properties and none of the content. For a row of a
database that is the whole story, and it is the cheap call.
`pages_retrieve_markdown` returns the content as Markdown, rendered by Notion.
One call, no recursion, and the result reads like a document. Reach for it
whenever the goal is to understand a page rather than edit a specific block.
`blocks_children_list` returns the blocks, one level at a time. A child that
reports `has_children` needs another call with its own ID. Use it when you
intend to edit, since only blocks have the IDs `blocks_update` needs.
## Writing content
Notion accepts at most 100 blocks and two levels of nesting in one request, and
the schema says so rather than leaving it to a 400. The block model is three
tiers: a top-level block holds nested blocks, a nested block holds leaf blocks,
and a leaf block holds nothing. A `column` and a `column_list` only exist at the
top; a `table` cannot be a leaf, because a table is its rows.
Deeper trees are built by appending to the blocks that come back.
The same limit is why `pages_create` takes a `markdown` string as an
alternative. Notion parses it server-side into blocks, at any depth, which is
the shortest path from a document you already have to a page that holds it.
## Querying a database
`data_sources_query` takes a filter built from one condition per column type,
composed with `and` and `or`. Both are Python keywords, so the fields are spelled
`and_` and `or_` in Python and go out under Notion's own names:
```python theme={null}
rows = await notion.data_sources_query.ainvoke(
data_source_id=DATA_SOURCE_ID,
body={
"filter": {
"and": [
{"property": "Status", "status": {"equals": "Done"}},
{"property": "Cost", "number": {"greater_than": 100}},
]
},
"sorts": [{"property": "Cost", "direction": "descending"}],
},
)
```
A filter naming a column that does not exist is a 400, so read the schema with
`data_sources_retrieve` first when you do not already know the column names.
## What the response handlers drop
Notion has no plain strings. Every piece of text is an array of runs, and each
run carries its annotations, a `plain_text` copy, an `href` and a type tag, so a
one-line title is about 200 bytes of JSON for about 20 characters of title. A row
repeats that per column and adds two user objects, two timestamps, a parent and
two URLs.
Every read tool projects: a run array becomes the string it spells, a property
becomes its value, a select becomes its name. Nothing is filtered, because a
shorter page would corrupt the length a paginated walk depends on, and every
`id` is kept, because that is what the next call needs.
`data_sources_retrieve` is the exception that proves it. There the schema is the
payload, so the columns are kept in full and only the per-option IDs and colours
go.
## Known limits
**Sending file bytes is not a tool.** A file becomes Notion-hosted content in
three steps, and the middle one takes `multipart/form-data` with raw bytes,
which Charter does not encode and which a model has no way to supply. The other
four upload endpoints are here, and `mode="external_url"` completes without that
step: Notion fetches the file from a public URL itself.
**Coverage is the content API.** Users, pages, blocks, databases, data sources,
search, comments, file uploads, custom emojis and async tasks. Notion's agent
and session platform, the Views API and meeting notes are not modelled, and
neither are the OAuth token endpoints, which belong to an authorization server
rather than to a tool.
**`pages_create` carries a large schema.** Every block type is reachable from
it, which is 87KB of JSON schema. That is the cost of being able to write any
block rather than the popular six. Narrow it at the point of use with
[`Tool.derived`](/charter/charter/reference/tool#tool-derived) when an agent only needs a few.