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

logger = logging.getLogger(__name__) 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.

parent may be any suitable ObjectReference type.

delete(block: Block | UUID | str) -> Block

Delete (archive) the specified Block.

block may be any suitable ObjectReference type.

restore(block: Block | UUID | str) -> Block

Restore (unarchive) the specified Block.

block may be any suitable ObjectReference type.

retrieve(block: Block | UUID | str) -> Block

Return the requested Block.

block may be any suitable ObjectReference type.

update(block: Block) -> Block

Update the block content on the server.

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

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: dict[str, PropertyType], title: list[RichTextBaseObject] | None = None) -> Database

Add a database to the given Page parent.

parent may be any suitable PageRef type.

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.

dbref may be any suitable DatabaseRef type.

update(db: Database, title: list[RichTextBaseObject] | None = None, description: list[RichTextBaseObject] | None = None, schema: dict[str, PropertyType] | 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

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 property

Return the underlying endpoint in the Notion SDK

PropertiesEndpoint(api: NotionAPI)

Interface to the API 'pages/properties' endpoint.

raw_api property

Return the underlying endpoint in the Notion SDK

retrieve(page_id, property_id)

Return the Property on a specific Page with the given ID

create(parent, title: Title | None = None, properties=None, children=None) -> Page

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

parent may be a ParentRef, Page, or Database object.

delete(page: Page) -> Page

Delete (archive) the specified Page.

page may be any suitable PageRef type.

restore(page: Page) -> Page

Restore (unarchive) the specified Page.

page may be any suitable PageRef type.

retrieve(page: Page | UUID | str) -> Page

Return the requested Page.

page may be any suitable PageRef type.

set_attr(page: Page, *, cover: FileObject | None | T_UNSET = UNSET, icon: FileObject | EmojiObject | None | T_UNSET = 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) -> Page

Update the Page object properties on the server.

An optional properties may be specified as "name": PropertyValue pairs.

If properties are provided, only those values will be updated. If properties is empty, all page properties will be updated.

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

SearchEndpoint(api: NotionAPI)

Interface to the API 'search' endpoint.

__call__(text=None) -> SearchQueryBuilder

Perform a search with the optional text

SessionError(message)

Raised when there are issues with the Notion session.

UsersEndpoint(api: NotionAPI)

Interface to the API 'users' endpoint.

raw_api 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_id) -> User

Return the User with the given ID.