Session management

This page covers advanced session configuration: custom HTTP clients, API version pinning and connection lifecycle details.

The Paperless constructor

Paperless(
    url: str,
    token: str | None = None,
    *,
    client: httpx.AsyncClient | None = None,
    request_api_version: int | None = None,
)

Lifecycle

Context manager

The recommended approach — initialize() and close() are called automatically:

async with Paperless("localhost:8000", "your-api-token") as paperless:
    # fully initialised here
    ...
# connection closed here

Manual

paperless = Paperless("localhost:8000", "your-api-token")
await paperless.initialize()

try:
    # use paperless
    pass
finally:
    await paperless.close()

What initialize() does

1. Sends a GET request to /api/schema/ to verify connectivity and authentication.
2. Reads the x-api-version and x-version response headers.
3. Sets is_initialized = True.

Any connectivity or authentication problem raises an exception before is_initialized becomes True. See Exceptions for details.

Custom HTTP client

You can supply your own httpx.AsyncClient. This is useful when you need to:

• Configure timeouts, retries or proxy settings
• Reuse an existing client for connection pooling
• Inject custom headers or SSL certificates

import httpx
from pypaperless import Paperless

custom_client = httpx.AsyncClient(
    timeout=httpx.Timeout(30.0),
    verify="/path/to/ca-bundle.pem",
    headers={"X-Custom-Header": "value"},
)

async with Paperless("localhost:8000", "your-api-token", client=custom_client) as paperless:
    ...

Pinning the API version

By default, pypaperless negotiates the API version from the x-api-version response header (currently targeting version 9). You can override this:

paperless = Paperless("localhost:8000", "your-api-token", request_api_version=8)

This can be useful when connecting to an older Paperless-ngx release that does not yet support the latest API version.

Logging

pypaperless uses the standard Python logging module under the logger name pypaperless.

import logging
logging.basicConfig(level=logging.DEBUG)

The library logs INFO-level messages for initialize() and close() events.

Available resources

After initialisation, the following services are available on the Paperless instance:

See Resources for the full feature matrix.