Skip to content

Endpoints

endpoints

Provides an object-based Notion API with all endpoints.

This pydantic based API is often referred to as just api while the low-level API of the Notion Client SDK library is just referred to as raw_api.

T_UNSET: TypeAlias = Literal['UNSET'] module-attribute

UNSET: T_UNSET = 'UNSET' module-attribute

BlocksEndpoint(*args, **kwargs)

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)

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: list[Block], *, after: Block | None = None) -> tuple[list[Block], 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) -> Block

Update the block content on the server.

The block info will be updated to the latest version from the server.

CommentsEndpoint(api: NotionAPI)

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: list[RichTextBaseObject]) -> Comment

Append a comment to the specified discussion.

create(page: Page | UUID | str, rich_text: 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.

DatabasesEndpoint(api: NotionAPI)

Interface to the 'databases' endpoint of the Notion API.

raw_api: NCDatabasesEndpoint property

Return the underlying endpoint in the Notion SDK.

create(parent: Page, schema: Mapping[str, PropertyType], title: list[RichTextBaseObject] | None = None) -> Database

Add a database to the given Page parent.

delete(db: Database) -> Database

Delete (archive) the specified Database.

query(db: Database | UUID | str) -> DBQueryBuilder

Initialize a new Query object with the target data class.

restore(db: Database) -> Database

Restore (unarchive) the specified 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, schema: Mapping[str, PropertyType | RenameProp] | None = None) -> Database

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)

Baseclass of the Notion API endpoints.

api = api 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

databases = DatabasesEndpoint(self) instance-attribute

pages = PagesEndpoint(self) instance-attribute

search = SearchEndpoint(self) instance-attribute

users = UsersEndpoint(self) instance-attribute

PagesEndpoint(*args, **kwargs)

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)

Interface to the API 'pages/properties' endpoint.

raw_api: NCPagesPropertiesEndpoint property

Return the underlying endpoint in the Notion SDK

retrieve(page: Page | UUID | str, property: PropertyValue | str) -> Iterator[PropertyItem]

Return the Property on a specific Page with the given ID

create(parent: ParentRef | Page | Database, title: Title | None = None, properties: dict[str, PropertyValue] | None = None, children: list[Block] | None = None) -> Page

Add a page to the given parent (Page or Database).

delete(page: Page) -> Page

Delete (archive) the specified Page.

restore(page: Page) -> Page

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 | T_UNSET | None = UNSET, icon: FileObject | EmojiObject | T_UNSET | None = UNSET, in_trash: bool | T_UNSET = UNSET) -> Page

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: PropertyValue) -> Page

Update the Page object properties on the server.

SearchEndpoint(api: NotionAPI)

Interface to the API 'search' endpoint.

__call__(text=None) -> SearchQueryBuilder

Perform a search with the optional text

UsersEndpoint(api: NotionAPI)

Interface to the API 'users' endpoint.

raw_api: NCUsersEndpoint property

Return the underlying endpoint in the Notion SDK

list() -> Iterator[User]

Return an iterator for all users in the workspace.

me() -> User

Return the current bot User.

retrieve(user: User | UUID | str) -> User

Return the User with the given ID.