Endpoints
endpoints ¶
Provides an object-based Notion API with all endpoints.
This pydantic based API is often referred to as api while the low-level API of the Notion Client SDK library is referred to as raw_api.
BlocksEndpoint(*args: Any, **kwargs: Any) ¶
Interface to the 'blocks' endpoint of the Notion API
children = BlocksEndpoint.ChildrenEndpoint(*args, **kwargs) instance-attribute ¶
raw_api: NCBlocksEndpoint property ¶
Return the underlying endpoint in the Notion SDK.
ChildrenEndpoint(api: NotionAPI) dataclass ¶
Interface to the API 'blocks/children' endpoint.
raw_api: NCBlocksChildrenEndpoint property ¶
Return the underlying endpoint in the Notion SDK.
append(parent: ParentRef | GenericObject | UUID | str, blocks: builtins.list[Block], *, after: Block | None = None) -> tuple[builtins.list[Block], builtins.list[Block]] ¶
Add the given blocks as children of the specified parent.
The blocks info of the passed blocks will be updated and returned as first part of a tuple. The second party of the tuple is an empty list or the updated blocks after the specified block if after was specified. Use this to update the blocks with the latest version from the server.
list(parent: ParentRef | GenericObject | UUID | str) -> Iterator[Block] ¶
Return all Blocks contained by the specified parent.
delete(block: Block | UUID | str) -> Block ¶
Delete (archive) the specified Block.
restore(block: Block | UUID | str) -> Block ¶
Restore (unarchive) the specified Block.
retrieve(block: Block | UUID | str) -> Block ¶
Return the requested Block.
update(block: Block) -> None ¶
Update the block object on the server.
The block info will be updated to the latest version from the server.
CommentsEndpoint(api: NotionAPI) dataclass ¶
Interface to the API 'comments' endpoint.
raw_api: NCCommentsEndpoint property ¶
Return the underlying endpoint in the Notion SDK
append(discussion_id: UUID | str, rich_text: builtins.list[RichTextBaseObject]) -> Comment ¶
Append a comment to the specified discussion.
create(page: Page | UUID | str, rich_text: builtins.list[RichTextBaseObject]) -> Comment ¶
Create a comment on the specified Page.
list(block: Block | Page | UUID | str) -> Iterator[Comment] ¶
Return all comments on the specified page or block.
DataSourcesEndpoint(api: NotionAPI) dataclass ¶
Interface to the 'data_sources' endpoint of the Notion API (new in API 2025-09-03).
Data sources contain the schema (properties) and pages. In API version 2025-09-03+, databases are containers that can hold multiple data sources, while data sources hold the actual data.
raw_api: NCDataSourcesEndpoint property ¶
Return the underlying endpoint in the Notion SDK.
create(parent: Database, schema: Mapping[str, Property], *, title: list[RichTextBaseObject] | None = None) -> DataSource ¶
Add an additional data source to an existing database container.
In API version 2025-09-03+ a data source's parent is always a database. To create the first data source under a page, create the database via DatabasesEndpoint.create (which seeds it with an initial data source); this endpoint only adds further data sources to a database that already exists.
delete(ds: DataSource) -> DataSource ¶
Delete (archive) the database containing the specified DataSource.
query(ds: DataSource | UUID | str) -> DataSourceQueryBuilder ¶
Initialize a new Query object for the data source.
restore(ds: DataSource) -> DataSource ¶
Restore (unarchive) the database containing the specified DataSource.
retrieve(dsref: DataSource | str | UUID) -> DataSource ¶
Return the DataSource with the given ID.
update(ds: DataSource, *, parent: SerializeAsAny[ParentRef] | None = None, title: list[RichTextBaseObject] | None = None, description: list[RichTextBaseObject] | None = None, inline: bool | None = None, schema: Mapping[str, Property | RenameProp | None] | None = None, in_trash: bool | None = None) -> None ¶
Update the DataSource object on the server.
The data source info will be updated to the latest version from the server. Passing a parent (a DatabaseRef) reassigns the data source to a different parent database. Pass in_trash=True/False to trash or restore an individual data source (the data source's containing database is left untouched).
API reference: https://developers.notion.com/reference/update-a-data-source
DatabasesEndpoint(api: NotionAPI) dataclass ¶
Interface to the 'databases' endpoint of the Notion API.
In API version 2025-09-03+, databases are containers that can hold multiple data sources. The actual schema/properties are now on the DataSource objects.
Note: Query functionality has moved to DataSourcesEndpoint.query().
raw_api: NCDatabasesEndpoint property ¶
Return the underlying endpoint in the Notion SDK.
create(parent: Page, *, schema: Mapping[str, Property] | None = None, title: list[RichTextBaseObject] | None = None, inline: bool = False) -> Database ¶
Create a new database container in the given Page parent.
In API version 2025-09-03+ a database is created together with its first data source, whose schema (properties) is passed via the initial_data_source payload. This is the only supported way to create a data source under a page; the data_sources endpoint only adds further data sources to an existing database.
retrieve(dbref: Database | str | UUID) -> Database ¶
Return the Database with the given ID.
update(db: Database, *, title: list[RichTextBaseObject] | None = None, description: list[RichTextBaseObject] | None = None, inline: bool | None = None, is_locked: bool | None = None) -> None ¶
Update the Database object on the server.
The database info will be updated to the latest version from the server.
API reference: https://developers.notion.com/reference/update-a-database
Endpoint(api: NotionAPI) dataclass ¶
Baseclass of the Notion API endpoints.
api: NotionAPI instance-attribute ¶
NotionAPI(client: NCClient) ¶
Object-based Notion API (pydantic) with all endpoints.
blocks = BlocksEndpoint(self) instance-attribute ¶
client = client instance-attribute ¶
comments = CommentsEndpoint(self) instance-attribute ¶
data_sources = DataSourcesEndpoint(self) instance-attribute ¶
databases = DatabasesEndpoint(self) instance-attribute ¶
pages = PagesEndpoint(self) instance-attribute ¶
search = SearchEndpoint(self) instance-attribute ¶
uploads = UploadsEndpoint(self) instance-attribute ¶
users = UsersEndpoint(self) instance-attribute ¶
PagesEndpoint(*args: Any, **kwargs: Any) ¶
Interface to the API 'pages' endpoint.
properties = PagesEndpoint.PropertiesEndpoint(*args, **kwargs) instance-attribute ¶
raw_api: NCPagesEndpoint property ¶
Return the underlying endpoint in the Notion SDK
PropertiesEndpoint(api: NotionAPI) dataclass ¶
create(parent: ParentRef | Page | DataSource, *, title: Title | None = None, properties: dict[str, PropertyValue] | None = None, children: list[Block] | None = None, cover: FileObject | None = None, icon: FileObject | EmojiObject | CustomEmojiObject | None = None) -> Page ¶
Add a page to the given parent (Page or DataSource).
delete(page: Page) -> None ¶
Delete (archive) the specified Page.
restore(page: Page) -> None ¶
Restore (unarchive) the specified Page.
retrieve(page: Page | UUID | str) -> Page ¶
Return the requested Page.
Warning
This method will only retrieve up to 25 items per property. Use pages.properties.retrieve to retrieve all items of a specific property.
set_attr(page: Page, *, cover: FileObject | UnsetType | None = Unset, icon: FileObject | EmojiObject | CustomEmojiObject | UnsetType | None = Unset, in_trash: bool | UnsetType = Unset, is_locked: bool | UnsetType = Unset) -> None ¶
Set specific page attributes (such as cover, icon, etc.) on the server.
page may be any suitable PageRef type.
To remove an attribute, set its value to None.
update(page: Page, *, properties: dict[str, PropertyValue] | None = None, cover: FileObject | UnsetType | None = Unset, icon: FileObject | EmojiObject | CustomEmojiObject | UnsetType | None = Unset, in_trash: bool | UnsetType = Unset, is_locked: bool | UnsetType = Unset) -> None ¶
Update the Page object properties on the server.
SearchEndpoint(api: NotionAPI) dataclass ¶
Interface to the API 'search' endpoint.
__call__(text: str | None = None) -> SearchQueryBuilder ¶
Perform a search with the optional text
UploadsEndpoint(api: NotionAPI) dataclass ¶
Interface to the API 'file uploads' endpoint.
raw_api: NCFileUploadsEndpoint property ¶
Return the underlying endpoint in the Notion SDK
complete(file_upload: FileUpload) -> None ¶
Complete the file upload and update the file_upload object.
create(name: str | None = None, n_parts: int | None = None, mode: FileUploadMode = FileUploadMode.SINGLE_PART, external_url: str | None = None, content_type: str | None = None) -> FileUpload ¶
Create a file upload.
list(status: FileUploadStatus | None = None, page_size: int = 100) -> Iterator[FileUpload] ¶
Return all file uploads.
retrieve(upload_id: UUID | str) -> FileUpload ¶
Return the FileUpload with the given ID.
send(file_upload: FileUpload, file: BinaryIO, part: int | None = None) -> None ¶
Send a file upload and update the file_upload object.
UsersEndpoint(api: NotionAPI) dataclass ¶
Interface to the API 'users' endpoint.