tessl/pypi-notion-client
Python client for the official Notion API
—
Pending
api-endpoints.mddocs/
API Endpoints
Complete interface to all Notion API endpoints including databases, pages, blocks, users, search, comments, and file uploads. Each endpoint provides CRUD operations with proper parameter handling and supports both synchronous and asynchronous usage.
Capabilities
Database Operations
Interface for working with Notion databases including querying, creating, updating, and retrieving database information.
class DatabasesEndpoint:
"""Database operations endpoint."""
def query(self, database_id, **kwargs):
"""
Get a list of Pages contained in the database.
Parameters:
- database_id: str, database ID
- filter: dict, query filter conditions
- sorts: list, sort configuration
- start_cursor: str, pagination cursor
- page_size: int, number of results per page (max 100)
- archived: bool, whether to include archived pages
- in_trash: bool, whether to include pages in trash
- filter_properties: list, properties to include in response
- auth: str, optional auth token for this request
Returns:
Dict with 'results' list of page objects and pagination info
"""
def retrieve(self, database_id, **kwargs):
"""
Retrieve a Database object using the ID specified.
Parameters:
- database_id: str, database ID
- auth: str, optional auth token for this request
Returns:
Database object dict
"""
def create(self, **kwargs):
"""
Create a database as a subpage in the specified parent page.
Parameters:
- parent: dict, parent page reference
- title: list, database title as rich text
- description: list, database description as rich text
- properties: dict, database schema properties
- icon: dict, database icon
- cover: dict, database cover image
- is_inline: bool, whether database is inline
- auth: str, optional auth token for this request
Returns:
Created database object dict
"""
def update(self, database_id, **kwargs):
"""
Update an existing database as specified by the parameters.
Parameters:
- database_id: str, database ID
- properties: dict, updated database schema properties
- title: list, updated database title as rich text
- description: list, updated database description as rich text
- icon: dict, updated database icon
- cover: dict, updated database cover image
- is_inline: bool, whether database is inline
- archived: bool, whether to archive the database
- in_trash: bool, whether to move database to trash
- auth: str, optional auth token for this request
Returns:
Updated database object dict
"""
def list(self, **kwargs):
"""
List all Databases shared with the authenticated integration.
DEPRECATED: This endpoint is deprecated.
Parameters:
- start_cursor: str, pagination cursor
- page_size: int, number of results per page
- auth: str, optional auth token for this request
Returns:
Dict with 'results' list of database objects and pagination info
"""Page Operations
Interface for creating, retrieving, and updating Notion pages and their properties.
class PagesEndpoint:
"""Page operations endpoint."""
# Sub-endpoint for page properties
properties: PagesPropertiesEndpoint
def create(self, **kwargs):
"""
Create a new page in the specified database or as a child of an existing page.
Parameters:
- parent: dict, parent reference (database_id or page_id)
- properties: dict, page property values
- children: list, child block objects to add
- icon: dict, page icon
- cover: dict, page cover image
- auth: str, optional auth token for this request
Returns:
Created page object dict
"""
def retrieve(self, page_id, **kwargs):
"""
Retrieve a Page object using the ID specified.
Parameters:
- page_id: str, page ID
- filter_properties: list, properties to include in response
- auth: str, optional auth token for this request
Returns:
Page object dict
"""
def update(self, page_id, **kwargs):
"""
Update page property values for the specified page.
Parameters:
- page_id: str, page ID
- properties: dict, updated property values
- icon: dict, updated page icon
- cover: dict, updated page cover image
- archived: bool, whether to archive the page
- in_trash: bool, whether to move page to trash
- auth: str, optional auth token for this request
Returns:
Updated page object dict
"""
class PagesPropertiesEndpoint:
"""Page property operations endpoint."""
def retrieve(self, page_id, property_id, **kwargs):
"""
Retrieve a property_item object for a given page_id and property_id.
Parameters:
- page_id: str, page ID
- property_id: str, property ID
- start_cursor: str, pagination cursor for property values
- page_size: int, number of results per page
- auth: str, optional auth token for this request
Returns:
Property item object dict
"""Block Operations
Interface for working with Notion blocks including retrieval, updates, deletion, and managing block children.
class BlocksEndpoint:
"""Block operations endpoint."""
# Sub-endpoint for block children
children: BlocksChildrenEndpoint
def retrieve(self, block_id, **kwargs):
"""
Retrieve a Block object using the ID specified.
Parameters:
- block_id: str, block ID
- auth: str, optional auth token for this request
Returns:
Block object dict
"""
def update(self, block_id, **kwargs):
"""
Update the content for the specified block_id based on the block type.
Parameters:
- block_id: str, block ID
- type: str, block type
- archived: bool, whether to archive the block
- in_trash: bool, whether to move block to trash
- [block_type]: dict, block-specific content (e.g., paragraph, heading_1, etc.)
- auth: str, optional auth token for this request
Supported block types:
- paragraph, heading_1, heading_2, heading_3
- bulleted_list_item, numbered_list_item, to_do, toggle
- quote, callout, code, equation, divider
- bookmark, embed, image, video, file, pdf, audio
- table, table_row, column, table_of_contents
- breadcrumb, link_to_page, template, synced_block
Returns:
Updated block object dict
"""
def delete(self, block_id, **kwargs):
"""
Set a Block object, including page blocks, to archived: true.
Parameters:
- block_id: str, block ID
- auth: str, optional auth token for this request
Returns:
Archived block object dict
"""
class BlocksChildrenEndpoint:
"""Block children operations endpoint."""
def list(self, block_id, **kwargs):
"""
Return a paginated array of child block objects contained in the block.
Parameters:
- block_id: str, parent block ID
- start_cursor: str, pagination cursor
- page_size: int, number of results per page
- auth: str, optional auth token for this request
Returns:
Dict with 'results' list of child block objects and pagination info
"""
def append(self, block_id, **kwargs):
"""
Create and append new children blocks to the block using the ID specified.
Parameters:
- block_id: str, parent block ID
- children: list, array of block objects to append
- after: str, block ID to insert children after
- auth: str, optional auth token for this request
Returns:
Dict with 'results' list of created block objects
"""User Operations
Interface for retrieving user information and workspace user lists.
class UsersEndpoint:
"""User operations endpoint."""
def list(self, **kwargs):
"""
Return a paginated list of Users for the workspace.
Parameters:
- start_cursor: str, pagination cursor
- page_size: int, number of results per page
- auth: str, optional auth token for this request
Returns:
Dict with 'results' list of user objects and pagination info
"""
def retrieve(self, user_id, **kwargs):
"""
Retrieve a User using the ID specified.
Parameters:
- user_id: str, user ID
- auth: str, optional auth token for this request
Returns:
User object dict
"""
def me(self, **kwargs):
"""
Retrieve the bot User associated with the API token.
Parameters:
- auth: str, optional auth token for this request
Returns:
Bot user object dict
"""Search Operations
Interface for searching pages and databases across the workspace.
class SearchEndpoint:
"""Search operations endpoint."""
def __call__(self, **kwargs):
"""
Search all pages and child pages that are shared with the integration.
Parameters:
- query: str, search query string
- sort: dict, sort configuration
- filter: dict, filter to limit search results
- start_cursor: str, pagination cursor
- page_size: int, number of results per page
- auth: str, optional auth token for this request
Returns:
Dict with 'results' list of matching page/database objects and pagination info
"""Comment Operations
Interface for creating and retrieving comments on pages and in discussion threads.
class CommentsEndpoint:
"""Comment operations endpoint."""
def create(self, **kwargs):
"""
Create a new comment in the specified page or existing discussion thread.
Parameters:
- parent: dict, parent page reference
- discussion_id: str, discussion thread ID (for threaded comments)
- rich_text: list, comment content as rich text
- auth: str, optional auth token for this request
Returns:
Created comment object dict
"""
def list(self, **kwargs):
"""
Retrieve a list of un-resolved Comment objects from the specified block.
Parameters:
- block_id: str, block ID to get comments for
- start_cursor: str, pagination cursor
- page_size: int, number of results per page
- auth: str, optional auth token for this request
Returns:
Dict with 'results' list of comment objects and pagination info
"""File Upload Operations
Interface for uploading files to Notion including creation, completion, and management of file uploads.
class FileUploadsEndpoint:
"""File upload operations endpoint."""
def create(self, **kwargs):
"""
Create a file upload.
Parameters:
- mode: str, upload mode ("single" or "multipart")
- filename: str, name of the file
- content_type: str, MIME type of the file
- number_of_parts: int, number of parts for multipart upload
- external_url: str, external URL for file (alternative to upload)
- auth: str, optional auth token for this request
Returns:
File upload object dict with upload URLs and metadata
"""
def complete(self, file_upload_id, **kwargs):
"""
Complete the file upload process.
Parameters:
- file_upload_id: str, file upload ID
- auth: str, optional auth token for this request
Returns:
Completed file upload object dict
"""
def retrieve(self, file_upload_id, **kwargs):
"""
Retrieve a file upload object using the ID specified.
Parameters:
- file_upload_id: str, file upload ID
- auth: str, optional auth token for this request
Returns:
File upload object dict
"""
def list(self, **kwargs):
"""
List all file uploads.
Parameters:
- status: str, filter by upload status
- start_cursor: str, pagination cursor
- page_size: int, number of results per page
- auth: str, optional auth token for this request
Returns:
Dict with 'results' list of file upload objects and pagination info
"""
def send(self, file_upload_id, **kwargs):
"""
Send a file upload.
Parameters:
- file_upload_id: str, file upload ID
- file: file-like object or tuple, file data to upload
- part_number: int, part number for multipart uploads
- auth: str, optional auth token for this request
Returns:
Upload response dict
"""Usage Examples
Database Operations
# Query database with filters
results = notion.databases.query(
database_id="database_id_here",
filter={
"and": [
{
"property": "Status",
"select": {"equals": "In Progress"}
},
{
"property": "Priority",
"number": {"greater_than": 1}
}
]
},
sorts=[
{
"property": "Created",
"direction": "descending"
}
]
)
# Create a new database
new_db = notion.databases.create(
parent={"page_id": "parent_page_id"},
title=[{"text": {"content": "Project Tasks"}}],
properties={
"Name": {"title": {}},
"Status": {
"select": {
"options": [
{"name": "Not Started", "color": "red"},
{"name": "In Progress", "color": "yellow"},
{"name": "Complete", "color": "green"}
]
}
},
"Priority": {"number": {}}
}
)Page Operations
# Create a new page in a database
page = notion.pages.create(
parent={"database_id": "database_id_here"},
properties={
"Name": {
"title": [{"text": {"content": "New Task"}}]
},
"Status": {
"select": {"name": "In Progress"}
},
"Priority": {
"number": 2
}
},
children=[
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{"text": {"content": "Task description here."}}]
}
}
]
)
# Update page properties
updated_page = notion.pages.update(
page_id="page_id_here",
properties={
"Status": {
"select": {"name": "Complete"}
}
}
)Block Operations
# Get block children
children = notion.blocks.children.list(block_id="block_id_here")
# Append new blocks
notion.blocks.children.append(
block_id="parent_block_id",
children=[
{
"object": "block",
"type": "heading_2",
"heading_2": {
"rich_text": [{"text": {"content": "New Section"}}]
}
},
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{"text": {"content": "Some content."}}]
}
}
]
)
# Update a block
updated_block = notion.blocks.update(
block_id="block_id_here",
paragraph={
"rich_text": [{"text": {"content": "Updated content."}}]
}
)Search Operations
# Search for pages containing specific text
search_results = notion.search(
query="project planning",
filter={
"value": "page",
"property": "object"
},
sort={
"direction": "descending",
"timestamp": "last_edited_time"
}
)
# Search within specific parent
search_results = notion.search(
query="meeting notes",
filter={
"value": "page",
"property": "object"
}
)File Upload Operations
# Create a file upload
with open("document.pdf", "rb") as file:
upload = notion.file_uploads.create(
mode="single",
filename="document.pdf",
content_type="application/pdf"
)
# Send the file data
notion.file_uploads.send(
file_upload_id=upload["id"],
file=file
)
# Complete the upload
completed = notion.file_uploads.complete(
file_upload_id=upload["id"]
)Install with Tessl CLI
npx tessl i tessl/pypi-notion-client