Skip to content

AsyncClient

AsyncClient 

AsyncClient(api_key: str | None = None, base_url: str = 'https://app.bloomgrowth.com/api/v1', timeout: float = 30.0, graphql_url: str | None = None)

Asynchronous client for interacting with the Bloomy API.

This client provides async access to all Bloomy API operations including users, meetings, todos, goals, headlines, issues, and scorecards.

client.v1 groups the REST API operations; the top-level attributes are aliases of client.v1.*, kept for backward compatibility. client.v2 groups the GraphQL API operations (user, meeting, issue, ...).

Parameters:

  • api_key (str | None, default: None ) –

    The API key for authentication. If not provided, it will be loaded from environment variables or configuration files.

  • base_url (str, default: 'https://app.bloomgrowth.com/api/v1' ) –

    The base URL for the API. Defaults to the production API URL.

Example

Using the async client with context manager:

import asyncio
from bloomy import AsyncClient

async def main():
    async with AsyncClient(api_key="your-api-key") as client:
        user = await client.user.details()
        print(user.name)

asyncio.run(main())

Without context manager:

client = AsyncClient(api_key="your-api-key")
user = await client.user.details()
await client.close()

Initialize the async Bloomy client.

Parameters:

  • api_key (str | None, default: None ) –

    The API key for authentication.

  • base_url (str, default: 'https://app.bloomgrowth.com/api/v1' ) –

    The base URL for the API.

  • timeout (float, default: 30.0 ) –

    The timeout in seconds for HTTP requests. Defaults to 30.0.

  • graphql_url (str | None, default: None ) –

    The absolute URL of the v2 GraphQL endpoint. Defaults to the scheme and host of base_url plus /graphql/.

Raises:

Methods:

  • __aenter__ –

    Enter the async context manager.

  • __aexit__ –

    Exit the async context manager.

  • close –

    Close the HTTP client.

Source code in src/bloomy/async_client.py 
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def __init__(
    self,
    api_key: str | None = None,
    base_url: str = "https://app.bloomgrowth.com/api/v1",
    timeout: float = 30.0,
    graphql_url: str | None = None,
) -> None:
    """Initialize the async Bloomy client.

    Args:
        api_key: The API key for authentication.
        base_url: The base URL for the API.
        timeout: The timeout in seconds for HTTP requests. Defaults to 30.0.
        graphql_url: The absolute URL of the v2 GraphQL endpoint. Defaults to
            the scheme and host of `base_url` plus `/graphql/`.

    Raises:
        ConfigurationError: If no API key is provided or found in configuration.

    """
    config = Configuration(api_key=api_key)

    if not config.api_key:
        raise ConfigurationError(
            "No API key provided. Set it explicitly, via BG_API_KEY "
            "environment variable, or in ~/.bloomy/config.yaml configuration file."
        )

    # Lazy imports to avoid circular dependencies
    from .v1 import AsyncV1
    from .v2 import AsyncV2, default_graphql_url

    if graphql_url is None:
        graphql_url = default_graphql_url(base_url)
    self._graphql_url = graphql_url

    self._client = httpx.AsyncClient(
        base_url=base_url,
        headers={
            "Authorization": f"Bearer {config.api_key}",
            "Content-Type": "application/json",
        },
        timeout=timeout,
    )

    # Initialize the v1 (REST) and v2 (GraphQL) operation namespaces,
    # sharing the same httpx client (v2 requests pass an absolute URL,
    # which overrides the client's base_url).
    self.v1: AsyncV1 = AsyncV1(self._client)
    self.v2: AsyncV2 = AsyncV2(self._client, self._graphql_url)

    # Top-level attributes are aliases of `self.v1.*` (same objects),
    # kept for backward compatibility.
    self.user: AsyncUserOperations = self.v1.user
    self.meeting: AsyncMeetingOperations = self.v1.meeting
    self.todo: AsyncTodoOperations = self.v1.todo
    self.goal: AsyncGoalOperations = self.v1.goal
    self.headline: AsyncHeadlineOperations = self.v1.headline
    self.issue: AsyncIssueOperations = self.v1.issue
    self.scorecard: AsyncScorecardOperations = self.v1.scorecard

Methods:

__aenter__ async 

__aenter__() -> Self

Enter the async context manager.

Returns:

  • Self –

    The async client instance.

Source code in src/bloomy/async_client.py 
129
130
131
132
133
134
135
136
137
async def __aenter__(self) -> Self:
    """Enter the async context manager.

    Returns:
        The async client instance.

    """
    await self._client.__aenter__()
    return self

__aexit__ async 

__aexit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) -> None

Exit the async context manager.

Source code in src/bloomy/async_client.py 
139
140
141
142
143
144
145
146
async def __aexit__(
    self,
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> None:
    """Exit the async context manager."""
    await self._client.__aexit__(exc_type, exc_val, exc_tb)

close async 

close() -> None

Close the HTTP client.

Source code in src/bloomy/async_client.py 
148
149
150
async def close(self) -> None:
    """Close the HTTP client."""
    await self._client.aclose()

Basic Usage

import asyncio
from bloomy import AsyncClient, ConfigurationError

async def main():
    # Initialize with API key
    async with AsyncClient(api_key="your-api-key") as client:
        users = await client.user.list()

    # Custom base URL (for testing/staging)
    async with AsyncClient(
        api_key="your-api-key",
        base_url="https://staging.example.com/api/v1"
    ) as client:
        users = await client.user.list()

    # Custom timeout (in seconds)
    async with AsyncClient(api_key="your-api-key", timeout=60.0) as client:
        users = await client.user.list()

    # Handle missing API key
    try:
        client = AsyncClient()
    except ConfigurationError as e:
        print(f"Configuration error: {e}")

asyncio.run(main())

Parameters

  • api_key (str, optional): Your Bloom Growth API key. If not provided, will attempt to load from BG_API_KEY environment variable or ~/.bloomy/config.yaml
  • base_url (str, optional): Custom API endpoint. Defaults to "https://app.bloomgrowth.com/api/v1"
  • timeout (float, optional): Request timeout in seconds. Defaults to 30.0

Exceptions

  • ConfigurationError: Raised when no API key can be found from any source

Context Manager

The AsyncClient supports async context manager protocol for automatic resource cleanup:

async with AsyncClient(api_key="your-api-key") as client:
    users = await client.user.list()
    # Client automatically closes when exiting the context