APIZ guide

Notion Adapter

Use the Notion Adapter when an agent needs the Notion API with resource-aware Policy actions. APIZ keeps the integration token inside the API Instance and supplies the configured Notion version header on upstream requests.

What This Adapter Supports

Pages, page properties and markdown, databases, data sources, and blocks.
Users, search, comments, file uploads, views, meeting notes, custom emoji, async tasks, and supported OAuth endpoints.
Official Notion API endpoint and version defaults.
APIZ bearer credentials for HTTP clients and compatible Notion SDK setup.
Semantic tests and a common-read template.

Credential Boundary

The Notion integration token is write-only API Instance credential material. The agent receives a different APIZ bearer credential, normally with an ntn_apiz_ prefix. APIZ removes caller authentication and injects the Notion token only after routing and Policy allow the request.

Notion page sharing controls what the integration can see. APIZ page/database hints make intended scope reviewable, but require Policy to become an additional enforced boundary.

Prepare The Upstream Credential

Create an internal Notion integration.
Grant only the integration capabilities the agent needs.
Share every required page or database with the integration in Notion.
Record the relevant page, database, data-source, or block IDs for tests and Policy resources.

An apparently valid token cannot access content that was not shared with its integration. Do not store the token in a workspace label, allowed-ID hint, or Policy fixture.

Web Console

Open API Instances → Create API Instance → Notion.
Enter a name and the write-only Integration token.
Add optional page and database IDs under Content hints.
Choose Token identity for the first test, or a resource-specific preset with its required ID.
Attach Allow Notion reads when the agent must not modify content.
Test the connection and save.

The default API endpoint and Notion version are under advanced settings. Change them only for a compatible controlled deployment.

CLI

apiz adapter explain notion

read -rsp "Notion integration token: " NOTION_TOKEN && printf '\n'
printf '%s' "$NOTION_TOKEN" | jq -Rs '{credential: .}' |
apiz -o json api create \
  --adapter notion \
  --name product-notion \
  --config-json '{"workspace_label":"Product","allowed_page_ids":["page-example"]}' \
  --test-config-json '{"preset":"get_token_user"}' \
  --credential-stdin
unset NOTION_TOKEN

Use a real page ID when selecting a page-specific connection test.

Give An Agent Access

apiz -o json client create --name knowledge-agent
apiz client bind <client-id> --api-instance <api-instance-id> --alias notion
apiz client credentials create <client-id> --binding notion --ttl 1h --format curl

The Web Console flow is Clients → Add Binding → Create Temporary Credentials. Attach a content Policy to the Notion Binding before issuance when the upstream integration can see more content than the agent should use. The generated bearer value is a Temporary Credential, not the Notion integration token.

Use It From The Agent

Search content visible to the integration:

curl -fsS \
  -H "Authorization: Bearer $APIZ_TEMPORARY_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"page_size":10}' \
  "$APIZ_NOTION_ENDPOINT/search"

For a Notion SDK, use the Setup Manifest endpoint as the API base URL and the APIZ credential as its bearer token when the SDK supports endpoint override. Do not put the upstream integration token in the agent environment.

Policy Actions And Resources

The adapter exposes semantic resources including notion_page, notion_page_property, notion_page_markdown, notion_database, notion_data_source, notion_block, notion_comment, notion_file_upload, notion_user, and notion_view.

Common actions include:

Need	Representative actions
Read pages and properties	`notion:page:retrieve`, `notion:page_property:retrieve`, `notion:page_markdown:retrieve`
Modify pages	`notion:page:create`, `notion:page:update`, `notion:page:move`, `notion:page_markdown:update`
Query structured content	`notion:database:retrieve`, `notion:data_source:query`, `notion:search`
Work with blocks	`notion:block:retrieve`, `notion:block:list_children`, `notion:block:append_children`, `notion:block:delete`
Comments	`notion:comment:list`, `notion:comment:create`, `notion:comment:update`, `notion:comment:delete`
Upload files	`notion:file_upload:create`, `notion:file_upload:send`, `notion:file_upload:complete`

Deletes and OAuth revocation are dangerous. Unknown future endpoints fall back to notion:endpoint:read or notion:endpoint:write. Run apiz adapter explain notion for the exact action catalog in the deployed release. Allow Notion reads admits the documented common read set and denies other actions.

Connection Tests

Preset	Required parameters	Behavior
`get_token_user`	none	Reads `/users/me`
`search`	none	Runs an empty search request
`get_page`	`page_id`	Reads one page
`get_database`	`database_id`	Reads one database
`get_block_children`	`block_id`	Lists one block's children

Every preset contacts Notion but is non-destructive. A 404 commonly means the resource was not shared with the integration, the ID is wrong, or the token cannot see it.

Evidence And Troubleshooting

Token identity succeeds but page test fails: share the page/database with the integration and verify the ID.
notion_connection_unauthorized: rotate a valid integration token with the required provider capabilities.
Page hint did not block another page: attach an enforced Policy; hints alone are not authorization.
A request uses unexpected semantics: inspect the normalized action and resource, especially fallback endpoint actions.

Use request evidence to confirm whether Notion was reached and which redacted status returned.

Current Limitations

APIZ does not automatically share Notion content with an integration.
The adapter does not run an OAuth authorization flow or refresh credentials.
Notion introduces API resources over time; unrecognized endpoints remain fail-closed through coarse fallback actions until the adapter is updated.