API Endpoints Reference

Fresh Complete list of Notion API endpoints.

Base URL

https://api.notion.com/v1

Authentication

All requests require:

Authorization: Bearer secret_xxxxxxxxxxxxx
Notion-Version: 2022-06-28
Content-Type: application/json

Endpoints Overview

Pages

Method	Endpoint	Description
POST	/pages	Create a page
GET	/pages/{page_id}	Retrieve a page
PATCH	/pages/{page_id}	Update page properties

Create Page

POST /pages

{
  "parent": { "database_id": "xxx" },
  "properties": {
    "Name": {
      "title": [{ "text": { "content": "New Page" } }]
    }
  }
}

Retrieve Page

GET /pages/{page_id}

Query parameters:

• filter_properties - Comma-separated property IDs to include

Update Page

PATCH /pages/{page_id}

{
  "properties": {
    "Status": { "select": { "name": "Done" } }
  }
}

Archive Page

PATCH /pages/{page_id}

{
  "archived": true
}

Databases

Method	Endpoint	Description
POST	/databases	Create a database
GET	/databases/{database_id}	Retrieve database schema
PATCH	/databases/{database_id}	Update database schema
POST	/databases/{database_id}/query	Query database pages

Create Database

POST /databases

{
  "parent": { "page_id": "xxx" },
  "title": [{ "text": { "content": "Tasks" } }],
  "properties": {
    "Name": { "title": {} },
    "Status": {
      "select": {
        "options": [
          { "name": "To Do", "color": "gray" },
          { "name": "Done", "color": "green" }
        ]
      }
    }
  }
}

Query Database

POST /databases/{database_id}/query

{
  "filter": {
    "property": "Status",
    "select": { "equals": "Done" }
  },
  "sorts": [
    { "property": "Created", "direction": "descending" }
  ],
  "page_size": 100,
  "start_cursor": "xxx"
}

Update Database

PATCH /databases/{database_id}

{
  "title": [{ "text": { "content": "Updated Title" } }],
  "properties": {
    "NewProperty": { "checkbox": {} }
  }
}

Blocks

Method	Endpoint	Description
GET	/blocks/{block_id}	Retrieve a block
PATCH	/blocks/{block_id}	Update a block
DELETE	/blocks/{block_id}	Delete (archive) a block
GET	/blocks/{block_id}/children	List child blocks
PATCH	/blocks/{block_id}/children	Append child blocks

Retrieve Block

GET /blocks/{block_id}

Update Block

PATCH /blocks/{block_id}

{
  "paragraph": {
    "rich_text": [{ "text": { "content": "Updated text" } }]
  }
}

Delete Block

DELETE /blocks/{block_id}

List Children

GET /blocks/{block_id}/children

Query parameters:

• start_cursor - Pagination cursor
• page_size - Results per page (max 100)

Append Children

PATCH /blocks/{block_id}/children

{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{ "text": { "content": "New paragraph" } }]
      }
    }
  ],
  "after": "block_id_to_insert_after"
}

Users

Method	Endpoint	Description
GET	/users	List all users
GET	/users/{user_id}	Retrieve a user
GET	/users/me	Get current bot user

List Users

GET /users

Query parameters:

• start_cursor - Pagination cursor
• page_size - Results per page (max 100)

Get Bot User

GET /users/me

Returns the bot user associated with the integration.

Search

Method	Endpoint	Description
POST	/search	Search pages and databases

Search

POST /search

{
  "query": "search term",
  "filter": {
    "value": "page",
    "property": "object"
  },
  "sort": {
    "direction": "descending",
    "timestamp": "last_edited_time"
  },
  "page_size": 100
}

Comments

Method	Endpoint	Description
POST	/comments	Create a comment
GET	/comments	List comments

Create Comment

POST /comments

{
  "parent": { "page_id": "xxx" },
  "rich_text": [{ "text": { "content": "Comment text" } }]
}

List Comments

GET /comments

Query parameters:

• block_id - Block or page ID (required)
• start_cursor - Pagination cursor
• page_size - Results per page

Pagination

All list endpoints support pagination:

Parameter	Description
page_size	Number of results (1-100, default varies)
start_cursor	Cursor from previous response

Response includes:

• has_more - Boolean indicating more results exist
• next_cursor - Cursor for next page (if has_more is true)

Pagination Example

async function fetchAll(queryFn) {
  const results = [];
  let cursor = undefined;

  do {
    const response = await queryFn(cursor);
    results.push(...response.results);
    cursor = response.has_more ? response.next_cursor : undefined;
  } while (cursor);

  return results;
}

Response Codes

Code	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists
429	Too Many Requests - Rate limited
500	Internal Server Error

See Also

• Objects Reference
• Errors Reference
• SOP 008: Handle Rate Limits