Skip to content

Integrations

Notion SDK: get started

The complete Notion API through typed application or agent clients

Use an ordinary App, or an Agent when the workload needs agent identity. Alter builds provider requests from a reviewed contract and applies the same connection authorization, policy, approvals, and audit records as raw requests.

Terminal window
npm install @alter-ai/sdk @alter-ai/notion
# Python (installs core automatically)
pip install alter-sdk-notion

The provider package includes only Notion types and response schemas and pins its contract version.

OAuth connections and managed secrets are supported. For a managed secret, store a Notion internal connection token or personal access token using the Notion template, then grant the application access. Share the relevant pages with the connection. Both kinds send Bearer authentication and the pinned Notion-Version: 2026-03-11 header.

Configure Notion, select the capabilities the application needs in Notion’s connection settings, and retain each customer’s grant ID after Connect consent. Alter supplies the credential; it never belongs in operation input.

import { App } from "@alter-ai/sdk";
import { NotionIntegration } from "@alter-ai/notion";
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const client = new NotionIntegration(app, { grantId: process.env.NOTION_GRANT_ID! });
const result = await (await client.users.getSelf({})).wait();
console.log(result.bodyJson());
} finally {
await app.close();
}
from alter_sdk import App
from alter_sdk_notion import NotionIntegration
async def first_call(api_key: str, grant_id: str):
async with App(api_key=api_key) as app:
client = NotionIntegration(app, {"grant_id": grant_id})
call = await client.users.get_self({})
result = await call.wait()
return result.body_json()

The current request schema uses in_trash for trashing pages, blocks, databases and data sources. Raw calls using the removed archived spelling are rejected; use the current field shown in discovery.

Contract 2026-11-12 publishes 58 operations from Notion’s official public OpenAPI document. OAuth token creation, revocation and introspection are excluded from the SDK: they require client authentication, and creation/revocation are refused by default. Creating/updating views, moving pages, updating data sources, and continuing sessions are also excluded because they can grant access through form settings, inherited permissions, or approval of an opaque agent action; ordinary raw edits remain governed by the reviewed request conditions. All 53 Admin API and 58 undocumented operations are inventoried separately with written exclusion reasons. Admin APIs require a different organization credential; Notion does not support undocumented APIs for production use. The API reference links every operation to its complete input fields, response models, TypeScript and Python examples, and policy identity. Browse by resource under this provider’s API reference in the Integrations sidebar, or download the pinned OpenAPI specification. The Developer Portal provider view and alter integrations operations notion --version 2026-11-03 also expose the schemas.

Generated calls pin the Alter contract version. Notion’s own product, role, scope and subscription requirements still apply. There is no silent version fallback and no automatic write retry or pagination.

Terminal window
alter integrations execute notion notion.post_search \
--version 2026-11-12 --grant "$NOTION_GRANT_ID" --input '{"body":{}}' --wait

Arguments use native path, query, headers, and body containers. Array query parameters are sent the way the provider’s document declares them: one delimited value where it declares explode: false (or a pipe- or space-delimited style), repeated keys otherwise. SDK methods preserve provider field names, decimal lexemes and large integers as strings when necessary. HTTP 204 returns null / None from the typed decoder. Binary responses use bodyBytes() / body_bytes(); the CLI can save them with --output-file.

A policy rule can require approval for any operation. The call returns a pending approval; wait() resolves once the approver decides, and resume(approvalId) picks a pending approval up after a restart. Approval cards show the operation, its contract version and the request input the sensitivity review marked safe to display.

File-upload send and skill-upload methods accept binary inputs as objects with filename, content_type, and content_base64. The adapter sends named multipart fields with the exact decoded bytes. Uploads may be frozen for approval: file content is encrypted with the held request and masked on approval surfaces. The shared proxy enforces a 5 MiB serialized-input ceiling.

Field overwrites are write; deleting, cancelling, archiving or disabling a whole resource adds delete. Content with external media or notifications carries send; fetching a caller-chosen URL counts as send. Agent-credit limits carry payment and agent configuration carries admin. Agent batches are expanded into separately governed actions. Starting a session can execute future agent tools whose effects cannot be known before dispatch, so its catalog declares the full mutating family union.

OAuth token creation, connection revocation and EMA access-token resolution are refused by default. The Admin API and the routes that need HTTP Basic auth are refused, because a connection’s token cannot call them. A request that grants a privilege carries the admin family, which a rule can deny or send to approval; privilege-granting routes are absent from SDKs. Internal-only routes remain cataloged for raw-call policy with explicit SDK exclusion reasons. Captures follow the application’s capture setting and shared masking. File bytes, external URLs, personal contact details, free-form document content and credentials are masked; raw card data is refused by the shared check. Notion signals whole-request failures through HTTP status codes. Partial batch outcomes remain available in the typed response.

The pinned official source, its hash, the generated methods and the policy mapping are checked together. Scheduled checks save upstream candidates and report additions, removals and schema changes; they never replace a published contract automatically. Existing contract versions remain available for installed SDKs and pending approvals.

Persist call.approvalId (TypeScript) or call.approval_id (Python), then construct a fresh provider client and call resume(savedId), followed by wait(). The stored approval selects the operation; this installed package verifies its provider and contract version before attaching the response validator. Mismatches raise ManagedOperationError, never silently decode using another contract. See persist-and-resume examples.

Policy operation fields also accept the published SDK function IDs listed by alter integrations operations notion. Use when.operation for a json_match or conditional require_approval rule, or match.operations for content_match (including redaction and step-up). Conditional approval can also use when.match.operations with parameter conditions. alter policy simulate --operation <function-id> tests that exact function.

Managed calls carry a server-verified function identity. Alter still evaluates policy against the actual method, URL and body after building the request from the authorized connection. Existing endpoint, method, host, catalog-operation and family rules continue to apply unchanged. A raw call can share an endpoint with several SDK functions and matches all of them; a function name never grants permission or bypasses existing restrictions.

For example, this rule requires approval for one function:

{
"effect": "require_approval",
"when": { "operation": "notion.post_search" },
"approval": { "approvers": ["reviewer@example.com"] }
}

Search is read-only; use notion.post_page to apply the same rule to page creation.

Save it with alter policy rules create --app <app-id> --grant <grant-id> --type require_approval --body @rule.json, or select the function in the portal.

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.