How to hit the Notion API

The Notion API lives at https://api.notion.com/v1. Every request needs a token and a Notion-Version header. An integration only sees pages you've explicitly shared with it.

Authentication

Create an internal integration at notion.so/profile/integrations and copy its secret. Then open each page or database you want it to reach and add the integration under ••• → Connections. Send the secret as Authorization: Bearer <token>. In the examples it's written {{NOTION_TOKEN}}.

Page and database ids are the 32-character hex string at the end of their URL.

Full reference: https://developers.notion.com/reference/intro

Retrieve a page

The page's properties. The content lives in its blocks — see /v1/blocks/{id}/children.

curl https://api.notion.com/v1/pages/{{PAGE_ID}} \
  -H "Authorization: Bearer {{NOTION_TOKEN}}" \
  -H "Notion-Version: 2026-03-11"
Run in PostTaco

Query a database

Databases hold one or more data sources; query the data source. Filters and sorts go in the body.

curl -X POST https://api.notion.com/v1/data_sources/{{DATA_SOURCE_ID}}/query \
  -H "Authorization: Bearer {{NOTION_TOKEN}}" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 10}'
Run in PostTaco

Create a page

A new child page under an existing page. title is the only property a plain page has.

curl -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer {{NOTION_TOKEN}}" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "{{PAGE_ID}}"},
    "properties": {"title": {"title": [{"text": {"content": "Created from PostTaco"}}]}}
  }'
Run in PostTaco

Append content to a page

Adds blocks to the end of a page (a page id works as a block id).

curl -X PATCH https://api.notion.com/v1/blocks/{{PAGE_ID}}/children \
  -H "Authorization: Bearer {{NOTION_TOKEN}}" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph",
       "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Hello from PostTaco"}}]}}
    ]
  }'
Run in PostTaco