Find pages/databases shared with the integration whose titles match a query. (docs)
POST /v1/search
🟢 low
— no
List the pages in a database, filtered and sorted. (docs)
POST /v1/databases/{database_id}/query
🟢 low
— no
What the agent can do
Capability
API call
Risk
Needs approval
Create a new page under a parent page/database, with properties and content. (docs)
POST /v1/pages
🟡 medium
✅ yes
Append up to 100 new child blocks to a page or block. (docs)
PATCH /v1/blocks/{block_id}/children
🟡 medium
✅ yes
Connecting it
You provide: Internal Integration Token or OAuth token
Where to get it: Notion → My Integrations → New integration → choose capabilities (Read/Update/Insert content) → copy the Internal Integration Secret. CRITICAL: each target page/database must be explicitly SHARED with the integration (page ••• menu → Add connections) or all calls return 403/404.
Permissions/scopes:read content, insert content
Account setup
Account needed: A Notion account (workspace owner privileges to create an internal integration).
App registration: Internal: My Integrations → New integration → select capabilities → copy the secret. THEN share each target page/database with the integration (••• → Add connections) — without this, every call fails 403/404. Public OAuth: register a public integration with redirect URI + capabilities, run the OAuth flow per workspace.
Verification required: No formal app-review process is documented for public integrations.
Testing: No separate sandbox — test with a free workspace + internal integration sharing one test page/database. The ~3 req/sec limit applies in testing too.
Limits
~3 requests/second average per integration (bursts allowed); HTTP 429 'rate_limited' with Retry-After on exceed.