Quick Start¶

What is sanhe_confluence_sdk?¶

sanhe_confluence_sdk is a Pythonic SDK for the Confluence REST API v2. It is designed with the following principles:

Everything is a Class: All requests and responses are represented as Python dataclasses with full type hints.
IDE Friendly: With complete type annotations, you get autocomplete and inline documentation in your IDE.
Access Raw Data: Every response object has a .raw_data attribute that gives you the original JSON dictionary if needed.
Consistent Pattern: All API calls follow the same pattern - create a Request, call .sync(client), get a Response.

Installation¶

pip install sanhe-confluence-sdk

Create a Client¶

To interact with the Confluence API, you first need to create a Confluence client. Currently, the SDK supports authentication via API Token (Basic Auth).

from sanhe_confluence_sdk.api import Confluence

# Create a client with your Confluence credentials
# - url: Your Atlassian site URL (e.g., https://your-domain.atlassian.net)
# - username: Your email address
# - password: Your API token (create one at https://id.atlassian.com/manage-profile/security/api-tokens)
client = Confluence(
    url="https://your-domain.atlassian.net",
    username="your-email@example.com",
    password="your-api-token",
)

Basic Usage¶

All API methods follow the same pattern:

Import the m module which provides lazy-loading access to all Request/Response classes
Create a Request object with the desired parameters
Call request.sync(client) to execute the request
Get a typed Response object back

Example - Get All Spaces¶

from sanhe_confluence_sdk.api import Confluence, m

# Create client
client = Confluence(
    url="https://your-domain.atlassian.net",
    username="your-email@example.com",
    password="your-api-token",
)

# Create a request to get spaces
request = m.GetSpacesRequest()

# Execute the request
response = request.sync(client)

# Access the results - fully typed!
for space in response.results:
    print(f"Space: {space.name} (key={space.key})")

# Need the raw JSON? Use .raw_data
print(response.raw_data)

Example - Get a Specific Page¶

For requests that require path parameters, import the PathParams class from the specific module:

from sanhe_confluence_sdk.api import Confluence
from sanhe_confluence_sdk.methods.page.get_page import (
    GetPageRequest,
    GetPageRequestPathParams,
)

client = Confluence(...)

# Create a request with path parameters
request = GetPageRequest(
    path_params=GetPageRequestPathParams(id=123456789),
)

response = request.sync(client)
print(f"Page title: {response.title}")
print(f"Page status: {response.status}")

Example - Create a New Page¶

For requests that require body parameters, import the BodyParams class:

from sanhe_confluence_sdk.api import Confluence
from sanhe_confluence_sdk.methods.page.create_page import (
    CreatePageRequest,
    CreatePageRequestBodyParams,
)

client = Confluence(...)

# Create a request with body parameters
request = CreatePageRequest(
    body_params=CreatePageRequestBodyParams(
        space_id="123456",
        title="My New Page",
        body={
            "representation": "storage",
            "value": "<p>Hello, Confluence!</p>",
        },
    ),
)

response = request.sync(client)
print(f"Created page: {response.id}")

Pagination¶

Many Confluence API endpoints return paginated results. The SDK provides a paginate() helper function to iterate through all pages of results.

from sanhe_confluence_sdk.api import Confluence, paginate
from sanhe_confluence_sdk.methods.space.get_spaces import (
    GetSpacesRequest,
    GetSpacesResponse,
)

client = Confluence(...)

# Create the initial request
request = GetSpacesRequest()

# Use paginate() to iterate through all pages
for response in paginate(
    client=client,
    request=request,
    response_type=GetSpacesResponse,
    page_size=25,      # Number of items per page
    max_items=100,     # Stop after fetching this many items
):
    for space in response.results:
        print(f"Space: {space.name}")

The paginate() function parameters:

client: Your Confluence client instance
request: The initial request object
response_type: The Response class type (e.g., GetSpacesResponse)
page_size: Number of items to fetch per page
max_items: Maximum total items to fetch (stops pagination when reached)
max_pages: Maximum number of pages to fetch (default: 100, safety limit)

What’s Next?¶

Check out the API Reference for all available Request/Response classes
Each Request class links to the official Atlassian API documentation in its docstring