Notion API and Knowledge Systems

Why it matters: Notion's API changed its object model (databases now contain data sources), and many tutorials are outdated. Knowing current concepts and how sharing works avoids "my token is valid but I get nothing" confusion.

By the end you can:

• Create and scope an integration
• Explain databases vs. data sources
• Query with filters and pagination
• Plan reconciliation

Learn (15 min)

1. Integrations see only what's shared (5 min)

A Notion integration is an app identity with capabilities (read, update, insert). It can access only pages/databases explicitly shared with it. Protect its secret. A valid token that returns empty results usually means the content wasn't shared with it.

2. Current object model (5 min)

A database can contain one or more data sources; the data source defines properties and holds rows (pages). Use the API version that supports data sources, and don't rely on older tutorials that query databases directly. Always check the API reference for the version you send in the Notion-Version header.

3. Query, paginate, write (5 min)

POST /v1/data_sources/{data_source_id}/query
Notion-Version: <a version that supports data sources>
Authorization: Bearer <integration secret>

{ "filter": { "property": "Status", "status": { "equals": "Approved" } },
  "sorts": [ { "property": "Publish date", "direction": "ascending" } ],
  "page_size": 50 }

Responses include has_more and next_cursor; pass start_cursor until done. Validate property types before writing, store a stable mapping from Notion page ID to your system's ID, and don't retry unsafe writes blindly.

Apply (15 min)

Worked example (3 min). Copy approved tasks to a reporting system: integration limited to read; share only the Tasks database; query Status = Approved; paginate; upsert by Notion page ID into reporting; nightly reconcile counts and spot-check 10 records; alert if counts differ.

Lab (7 min): Plan the integration.

1. Choose a database and list the 4 properties you'd read.
2. Write the filter and sort you'd send.
3. Describe your pagination loop and your stable ID mapping.
4. Define the reconciliation check and what triggers an alert.

Deliverable: A one-page integration plan. You're done when: Re-running it twice would not create duplicates.

Check yourself (5 min)

1. Does a token automatically see all pages?
2. What defines properties for the current model?
3. How do you continue a paginated query?
4. Scenario: A tutorial uses an old database-query endpoint and fails. What do you check?
5. What is reconciliation?

Reference

Common mistakes

Cheat sheet: Create integration → share specific content → current API version → query data source → paginate → validate → reconcile.

Key terms: integration, capability, data source, cursor, reconciliation.

Interview prompts: How would you sync Notion to a reporting system reliably?

Go deeper: Data sources · Retrieve a data source · Query a data source · API reference

Next: Lesson 25 — scheduling.