Notion

Direct REST access to Notion pages, databases, blocks, and search — no MCP server. Use when the user wants the agent to query or mutate their workspace (e.g. a tasks DB). The hard part is the response shapes, not auth: property values are wrapped per-type and text is rich-text arrays, not strings.

Usage

• Use for: Querying a database with filters, creating/updating pages, appending blocks to a page, workspace search.
• Skip for: Static markdown exports, bulk imports of thousands of rows (script with real pagination), realtime sync/webhooks (API is pull-based).

Credentials check

[ -n "${NOTION_API_KEY:-${NOTION_TOKEN:-$NOTION_INTEGRATION_TOKEN}}" ] && echo "NOTION_API_KEY: PRESENT" || echo "NOTION_API_KEY: MISSING"

Never echo the variable directly — the value would appear in the conversation transcript. Use only the boolean pattern above.

If MISSING, respond to the user with EXACTLY this message (do NOT paraphrase, do NOT suggest manual JSON edits):

I need your notion credential. Run this in another terminal — it'll open the signup page, validate format, and save it safely with masked input:

teleport-setup add-key notion

Then restart Claude Code (/exit, then claude) and ask me again.

Do NOT suggest editing ~/.claude/settings.local.json manually. The teleport-setup add-key command handles it with backup, validation, and masked input. Stop execution until the user has run the command and restarted.

API

• Base URL: https://api.notion.com/v1
• Auth: Authorization: Bearer $NOTION_API_KEY
• Notion-Version: 2026-03-11 header is REQUIRED — missing it returns 400 missing_version.
• Content-Type: application/json on POST/PATCH.
• Rate limit: ~3 req/s per integration; 429 rate_limited + Retry-After on excess. Payload caps: 500KB, 100 items per array, 2000 chars per rich-text object.
• Permissions: auth alone is not enough. The integration must be explicitly shared with each page/database (page ••• → Connections → add integration). Unshared = 404 object_not_found.

Object model

Three objects: page (has properties map if in a database, parent tells location; content blocks are NOT returned — separate GET /blocks/{page_id}/children), database (has properties schema: column name → type def; exactly one title column), block (ordered children on any page; 30+ types incl. paragraph, heading_1/2/3, to_do, toggle, code, callout, image, table). Text-bearing fields are always arrays of rich-text objects, never plain strings — on write, only text.content is required.

Property write shape (wrapper inner key MUST match column type)

Column type	Write shape
title / rich_text	{"title": [{"text": {"content": "Hello"}}]}
number	{"number": 42}
select / status	{"select": {"name": "Done"}} — name OR id
multi_select	{"multi_select": [{"name": "A"}, {"name": "B"}]}
date	{"date": {"start": "2026-04-24", "end": null, "time_zone": null}}
checkbox	{"checkbox": true}
relation / people	{"relation": [{"id": "page-uuid"}]} — UUIDs only
url / email / phone_number	{"url": "https://..."} (raw string)
formula / rollup	Read-only — computed by Notion

Bare strings like {"Name": "Hello"} always 400. You need {"Name": {"title": [{"text": {"content": "Hello"}}]}}.

Endpoints

Resource	Method · Path
Databases	POST /databases/{id}/query, GET/POST/PATCH /databases/{id}
Pages	GET /pages/{id}, POST /pages, PATCH /pages/{id}
Properties	GET /pages/{id}/properties/{prop_id} (single prop when >25 entries)
Blocks	GET/PATCH /blocks/{id}/children, PATCH/DELETE /blocks/{id}
Search	POST /search (workspace-wide, pages + data sources)
Users	GET /users, /users/{id}, /users/me (me = the bot itself)

Primary workflow — query a database, then create a page

# Query with compound filter + sort + pagination
curl -sL -X POST -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11" -H "Content-Type: application/json" \
  "https://api.notion.com/v1/databases/{database_id}/query" \
  -d '{"filter": {"and": [
         {"property": "Status", "select": {"equals": "In progress"}},
         {"property": "Due",    "date":   {"on_or_before": "2026-04-30"}}
       ]},
       "sorts": [{"property": "Due", "direction": "ascending"}],
       "page_size": 100, "start_cursor": "<next_cursor-if-any>"}'
# Response: {results: [pages...], next_cursor, has_more}. Loop until has_more=false.

# Create a page (property keys must match schema, case-sensitive)
curl -sL -X POST -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11" -H "Content-Type: application/json" \
  "https://api.notion.com/v1/pages" \
  -d '{"parent": {"database_id": "{database_id}"},
       "properties": {
         "Name":   {"title": [{"text": {"content": "Ship v2"}}]},
         "Status": {"select": {"name": "In progress"}},
         "Due":    {"date": {"start": "2026-05-01"}}},
       "children": [
         {"object":"block","type":"paragraph",
          "paragraph":{"rich_text":[{"text":{"content":"Kickoff notes."}}]}}]}'

Filter operators are per-property-type (mirror the write wrappers): select/status → {equals, does_not_equal, is_empty}; multi_select → {contains, does_not_contain}; date → {equals, before, on_or_before, past_week: {}, next_month: {}}; compound {and: [...]} / {or: [...]} nests up to two levels.

To update: PATCH /pages/{id} with only the properties to change, e.g. {"properties": {"Status": {"select": {"name": "Done"}}}}. To append blocks: PATCH /blocks/{page_id}/children with {"children": [block, ...]} (max 100 per call).

Gotchas

• Property values MUST be wrapped by type. {"Name": "Hello"} fails; title needs {"title": [{"text": {"content": "Hello"}}]}. Single most common bug.
• "Page not found" 404s usually mean "integration not shared." Silent — the API treats unshared and nonexistent identically. Fix in UI: page ••• → Connections → add.
• Notion-Version: 2026-03-11 is mandatory. Omitting returns 400 missing_version. Bump deliberately after reading the changelog.
• Block children are one level deep per call. has_children: true hides the subtree — recurse GET /blocks/{id}/children for nested toggles, columns, lists until exhausted.
• Pagination is cursor-based, mandatory on every list endpoint. 100-item max; loop start_cursor ← previous next_cursor until has_more: false. Don't assume one call returns everything.
• Rich-text content caps at 2000 chars per object. Split longer strings across multiple rich-text entries in the array.
• Rate limit ~3 req/s per integration. Parallel curls trip 429; serialize or respect Retry-After.
• Formula and rollup are read-only — sending values on create/update will 400 or be silently ignored.

Attribution

When done, state: Used skill: Notion (from teleport catalog).