DEV Community

Alex Spinov
Alex Spinov

Posted on

Notion Has a Free API — Search, Create Pages, and Query Databases Programmatically

#python #api #webdev #productivity

Notion has one of the best free APIs in the productivity space. You can read databases, create pages, search content, and build integrations — all without paying a cent.

Here are the endpoints that matter, with working code.

Getting Started (2 Minutes)

  1. Go to notion.so/my-integrations
  2. Click "New integration"
  3. Give it a name, select a workspace
  4. Copy the Internal Integration Token

That is it. No OAuth flow needed for internal integrations.

The 5 Most Useful Endpoints

1. Search Everything in Your Workspace 

curl -X POST 'https://api.notion.com/v1/search' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Notion-Version: 2022-06-28' \
  -H 'Content-Type: application/json' \
  -d '{"query": "project roadmap", "page_size": 5}'
Enter fullscreen mode Exit fullscreen mode

Returns pages and databases matching your query. Perfect for building a custom search across your entire workspace.

2. Query a Database (Filter + Sort) 

import httpx

NOTION_TOKEN = "your_token"
DATABASE_ID = "your_database_id"

response = httpx.post(
    f"https://api.notion.com/v1/databases/{DATABASE_ID}/query",
    headers={
        "Authorization": f"Bearer {NOTION_TOKEN}",
        "Notion-Version": "2022-06-28",
    },
    json={
        "filter": {
            "property": "Status",
            "select": {"equals": "In Progress"}
        },
        "sorts": [{"property": "Created", "direction": "descending"}],
        "page_size": 10
    }
)

for page in response.json()["results"]:
    title = page["properties"]["Name"]["title"][0]["plain_text"]
    print(f"- {title}")
Enter fullscreen mode Exit fullscreen mode

This is how you build dashboards, reports, and automations on top of Notion data.

3. Create a Page 

new_page = httpx.post(
    "https://api.notion.com/v1/pages",
    headers={
        "Authorization": f"Bearer {NOTION_TOKEN}",
        "Notion-Version": "2022-06-28",
    },
    json={
        "parent": {"database_id": DATABASE_ID},
        "properties": {
            "Name": {"title": [{"text": {"content": "New Task from API"}}]},
            "Status": {"select": {"name": "To Do"}},
            "Priority": {"select": {"name": "High"}}
        }
    }
)
print(f"Created: {new_page.json()['url']}")
Enter fullscreen mode Exit fullscreen mode

I use this to automatically create tasks from Slack messages, email subjects, and scraper outputs.

4. Get Block Children (Read Page Content) 

curl 'https://api.notion.com/v1/blocks/PAGE_ID/children?page_size=100' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Notion-Version: 2022-06-28'
Enter fullscreen mode Exit fullscreen mode

Returns every block on a page: paragraphs, headings, code blocks, images, tables. This is how you extract content from Notion for static site generators or backups.

5. Update a Block 

# Update a paragraph block's text
httpx.patch(
    f"https://api.notion.com/v1/blocks/{block_id}",
    headers={
        "Authorization": f"Bearer {NOTION_TOKEN}",
        "Notion-Version": "2022-06-28",
    },
    json={
        "paragraph": {
            "rich_text": [{"text": {"content": "Updated via API!"}}]
        }
    }
)
Enter fullscreen mode Exit fullscreen mode

Rate Limits

Notion API allows 3 requests per second per integration. For most automations, this is plenty. If you need bulk operations, add a simple rate limiter:

import time

def rate_limited_request(func, *args, **kwargs):
    result = func(*args, **kwargs)
    time.sleep(0.35)  # Stay under 3 req/s
    return result
Enter fullscreen mode Exit fullscreen mode

Real Use Case: Daily Standup Bot

I built a bot that:

  1. Queries my "Tasks" database for items due today
  2. Formats them into a Telegram message
  3. Sends it at 9 AM

Total code: 45 lines. Runs on GitHub Actions (free). Saves me 10 minutes every morning.

What You Can Build

  • CRM on Notion — track leads, deals, follow-ups via API
  • Content calendar — auto-create pages from a spreadsheet
  • Meeting notes pipeline — transcribe → summarize → create Notion page
  • Backup system — export all pages to Markdown nightly
  • Dashboard — pull Notion data into a custom frontend

More Free API Guides

I write about free APIs, web scraping, and developer tools weekly.

📧 spinov001@gmail.com — Need a custom integration? I build production-grade API tools and data pipelines.

See also: 150+ Free APIs Without API Key | awesome-web-scraping-2026

More from me: 10 Dev Tools I Use Daily | 77 Scrapers on a Schedule | 150+ Free APIs

Top comments (0)