Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท API and Integrations

Creating Pages and Blocks with the API

Learn the JSON for creating Notion pages in a database, updating properties and appending blocks such as headings and to-dos, with validators you can run.

Reading data is half the story. The other half is writing: adding a row to a database, changing a Status, or filling a page with headings and checklists. This lesson covers the three write calls you will use most, and gives you runnable checkers so you can see mistakes before the real API does.

As in the rest of this chapter, the live API is not reachable from this site. The JavaScript builds and validates example request bodies only; nothing is sent. Check the API reference for your version for the complete lists of property and block types.

Create a page in a database

POST /pages with a parent and properties:

JSON
{
  "parent": { "database_id": "YOUR_DATABASE_ID" },
  "properties": {
    "Name":     { "title": [ { "text": { "content": "Write the report" } } ] },
    "Status":   { "status": { "name": "Not started" } },
    "Priority": { "select": { "name": "High" } },
    "Due":      { "date": { "start": "2026-11-30" } },
    "Estimate": { "number": 3 }
  }
}

Rules to remember:

  • Property names must match the database exactly, including case and spaces.
  • Every database has one title property; you should always set it.
  • Select and status options by name must already exist (select options are often created on the fly, status options are not).
  • You can add children (an array of blocks) to put content into the new page in the same call, and icon and cover if you wish.

To create a child page of another page instead, use "parent": { "page_id": "..." }; then only title is allowed as a property.

Update a page

PATCH /pages/{page_id} with only the properties you want to change:

JSON
{ "properties": { "Status": { "status": { "name": "Done" } } } }

You can also archive a page with "archived": true (moves it to the trash, recoverable in the app).

Append blocks

PATCH /blocks/{block_id}/children adds blocks to the end of a page (a page's ID also works as a block ID):

JSON
{
  "children": [
    { "object": "block", "type": "heading_2",
      "heading_2": { "rich_text": [ { "type": "text", "text": { "content": "Plan" } } ] } },
    { "object": "block", "type": "to_do",
      "to_do": { "rich_text": [ { "type": "text", "text": { "content": "Draft outline" } } ], "checked": false } }
  ]
}

Each block has a type and an object of the same name holding its content. Text lives in a rich_text array of pieces that can each carry formatting (annotations) and links. Common types: paragraph, heading_1 to heading_3, bulleted_list_item, numbered_list_item, to_do, toggle, quote, callout, code, divider. There is a limit on blocks per request (around 100) and on the length of one text piece (around 2000 characters), so split big content.

Stand-in: builders for property and block JSON

Writing this JSON by hand invites typos. Small helper functions make it tidy. This block only builds objects.

JS Stand-in: JSON builders

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: a validator

This checker compares a body against a schema we define (names and types of properties). The real API reports similar errors as HTTP 400, but doing it first gives a quicker, clearer message.

JS Stand-in: validate before sending

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical advice

  • Idempotency: the API has no built-in "create if not exists". To avoid duplicates, query first (for example by an external ID property) and update if found.
  • Batch politely: loop with a short delay and handle 429 responses; do not fire hundreds of requests at once.
  • Large imports: build the JSON for each row from a CSV, log failures to a file, and keep going on error instead of stopping.
  • Rich text: link text is {"type":"text","text":{"content":"docs","link":{"url":"https://example.com"}}}.
  • Never write secrets into pages through the API; pages can be shared.

Notion's built-in CSV import is often quicker than the API for one-time loads. Use the API when the data keeps changing or needs transformation.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which call changes only the Status of an existing page?

    PATCH on the page with only the properties you want to change updates them.
  2. 2. What must property names in a create request match?

    Names must match the database schema exactly, or the API returns an error.
  3. 3. How do you put a heading and a checkbox in a page?

    Blocks such as heading_2 and to_do are appended as children of the page or another block.

Summary

  • POST /pages creates a page or row; set the title and match property names and types.
  • PATCH /pages/{id} updates properties or archives a page.
  • PATCH /blocks/{id}/children appends blocks made of typed rich-text content.
  • Use helper functions and a validator, avoid duplicates by checking first, and respect rate limits.

Next: PARA and the Second Brain