Client

Synchronous and asynchronous clients for Notion's API.

AsyncClient

Bases: BaseClient

Asynchronous client for Notion's API.

Source code in notion_client/client.py

class AsyncClient(BaseClient):
    """Asynchronous client for Notion's API."""

    client: httpx.AsyncClient

    def __init__(
        self,
        options: Optional[Union[Dict[str, Any], ClientOptions]] = None,
        client: Optional[httpx.AsyncClient] = None,
        **kwargs: Any,
    ) -> None:
        if client is None:
            client = httpx.AsyncClient()
        super().__init__(client, options, **kwargs)

    async def __aenter__(self) -> "AsyncClient":
        self.client = httpx.AsyncClient()
        await self.client.__aenter__()
        return self

    async def __aexit__(
        self,
        exc_type: Type[BaseException],
        exc_value: BaseException,
        traceback: TracebackType,
    ) -> None:
        await self.client.__aexit__(exc_type, exc_value, traceback)
        del self._clients[-1]

    async def aclose(self) -> None:
        """Close the connection pool of the current inner client."""
        await self.client.aclose()

    async def request(
        self,
        path: str,
        method: str,
        query: Optional[Dict[Any, Any]] = None,
        body: Optional[Dict[Any, Any]] = None,
        form_data: Optional[Dict[Any, Any]] = None,
        auth: Optional[str] = None,
    ) -> Any:
        """Send an HTTP request asynchronously."""
        request = self._build_request(method, path, query, body, form_data, auth)
        try:
            response = await self.client.send(request)
        except httpx.TimeoutException:
            raise RequestTimeoutError()
        return self._parse_response(response)

aclose() async

Close the connection pool of the current inner client.

Source code in notion_client/client.py

async def aclose(self) -> None:
    """Close the connection pool of the current inner client."""
    await self.client.aclose()

request(path, method, query=None, body=None, form_data=None, auth=None) async

Send an HTTP request asynchronously.

Source code in notion_client/client.py

async def request(
    self,
    path: str,
    method: str,
    query: Optional[Dict[Any, Any]] = None,
    body: Optional[Dict[Any, Any]] = None,
    form_data: Optional[Dict[Any, Any]] = None,
    auth: Optional[str] = None,
) -> Any:
    """Send an HTTP request asynchronously."""
    request = self._build_request(method, path, query, body, form_data, auth)
    try:
        response = await self.client.send(request)
    except httpx.TimeoutException:
        raise RequestTimeoutError()
    return self._parse_response(response)

Client

Bases: BaseClient

Synchronous client for Notion's API.

Source code in notion_client/client.py

class Client(BaseClient):
    """Synchronous client for Notion's API."""

    client: httpx.Client

    def __init__(
        self,
        options: Optional[Union[Dict[Any, Any], ClientOptions]] = None,
        client: Optional[httpx.Client] = None,
        **kwargs: Any,
    ) -> None:
        if client is None:
            client = httpx.Client()
        super().__init__(client, options, **kwargs)

    def __enter__(self) -> "Client":
        self.client = httpx.Client()
        self.client.__enter__()
        return self

    def __exit__(
        self,
        exc_type: Type[BaseException],
        exc_value: BaseException,
        traceback: TracebackType,
    ) -> None:
        self.client.__exit__(exc_type, exc_value, traceback)
        del self._clients[-1]

    def close(self) -> None:
        """Close the connection pool of the current inner client."""
        self.client.close()

    def request(
        self,
        path: str,
        method: str,
        query: Optional[Dict[Any, Any]] = None,
        body: Optional[Dict[Any, Any]] = None,
        form_data: Optional[Dict[Any, Any]] = None,
        auth: Optional[str] = None,
    ) -> Any:
        """Send an HTTP request."""
        request = self._build_request(method, path, query, body, form_data, auth)
        try:
            response = self.client.send(request)
        except httpx.TimeoutException:
            raise RequestTimeoutError()
        return self._parse_response(response)

close()

Close the connection pool of the current inner client.

Source code in notion_client/client.py

def close(self) -> None:
    """Close the connection pool of the current inner client."""
    self.client.close()

request(path, method, query=None, body=None, form_data=None, auth=None)

Send an HTTP request.

Source code in notion_client/client.py

def request(
    self,
    path: str,
    method: str,
    query: Optional[Dict[Any, Any]] = None,
    body: Optional[Dict[Any, Any]] = None,
    form_data: Optional[Dict[Any, Any]] = None,
    auth: Optional[str] = None,
) -> Any:
    """Send an HTTP request."""
    request = self._build_request(method, path, query, body, form_data, auth)
    try:
        response = self.client.send(request)
    except httpx.TimeoutException:
        raise RequestTimeoutError()
    return self._parse_response(response)

ClientOptions dataclass

Options to configure the client.

Attributes:

Name	Type	Description
auth	Optional[str]	Bearer token for authentication. If left undefined, the auth parameter should be set on each request.
timeout_ms	int	Number of milliseconds to wait before emitting a RequestTimeoutError.
base_url	str	The root URL for sending API requests. This can be changed to test with a mock server.
log_level	int	Verbosity of logs the instance will produce. By default, logs are written to stdout.
logger	Optional[Logger]	A custom logger.
notion_version	str	Notion version to use.

Source code in notion_client/client.py

@dataclass
class ClientOptions:
    """Options to configure the client.

    Attributes:
        auth: Bearer token for authentication. If left undefined, the `auth` parameter
            should be set on each request.
        timeout_ms: Number of milliseconds to wait before emitting a
            `RequestTimeoutError`.
        base_url: The root URL for sending API requests. This can be changed to test
            with a mock server.
        log_level: Verbosity of logs the instance will produce. By default, logs are
            written to `stdout`.
        logger: A custom logger.
        notion_version: Notion version to use.
    """

    auth: Optional[str] = None
    timeout_ms: int = 60_000
    base_url: str = "https://api.notion.com"
    log_level: int = logging.WARNING
    logger: Optional[logging.Logger] = None
    notion_version: str = "2025-09-03"