Client

The main entry point for interacting with the Bloomy API.

Client

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

The Client class is the main entry point for interacting with the Bloomy API.

It provides methods for managing Bloom Growth features.

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

Example

from bloomy import Client
client = Client()
client.meeting.list()
client.user.details()
client.meeting.delete(123)
client.scorecard.list()
client.issue.list()
client.headline.list()

# v2 (GraphQL)
client.v2.user.details()
client.v2.meeting.details(349524)
client.v2.issue.list(349524)

Initialize a new Client instance.

Parameters:

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

  The API key to use. If not provided, will attempt to load from environment variable (BG_API_KEY) or configuration file.

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

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

• 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:

• ConfigurationError –

  If no API key is provided or found in configuration.

Methods:

• __enter__ –

  Context manager entry.

• __exit__ –

  Context manager exit - close the HTTP client.

• close –

  Close the HTTP client connection.

Source code in src/bloomy/client.py

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 a new Client instance.

    Args:
        api_key: The API key to use. If not provided, will attempt to
                 load from environment variable (BG_API_KEY) or configuration file.
        base_url: The base URL for the API. Defaults to the production API URL.
        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.

    """
    # Use Configuration class which handles priority:
    # 1. Explicit api_key parameter
    # 2. BG_API_KEY environment variable
    # 3. Configuration file (~/.bloomy/config.yaml)
    self.configuration = Configuration(api_key)

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

    self._api_key = self.configuration.api_key
    self._base_url = base_url

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

    # Initialize HTTP client
    self._client = httpx.Client(
        base_url=base_url,
        headers={
            "Accept": "*/*",
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self._api_key}",
        },
        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 = V1(self._client)
    self.v2 = V2(self._client, self._graphql_url)

    # Top-level attributes are aliases of `self.v1.*` (same objects),
    # kept for backward compatibility.
    self.user = self.v1.user
    self.todo = self.v1.todo
    self.meeting = self.v1.meeting
    self.goal = self.v1.goal
    self.scorecard = self.v1.scorecard
    self.issue = self.v1.issue
    self.headline = self.v1.headline

Methods:

__enter__

__enter__() -> Self

Context manager entry.

Returns:

• Self –

  The client instance.

Source code in src/bloomy/client.py

def __enter__(self) -> Self:
    """Context manager entry.

    Returns:
        The client instance.

    """
    return self

__exit__

__exit__(*args: Any) -> None

Context manager exit - close the HTTP client.

Source code in src/bloomy/client.py

def __exit__(self, *args: Any) -> None:
    """Context manager exit - close the HTTP client."""
    self._client.close()

close

close() -> None

Close the HTTP client connection.

Source code in src/bloomy/client.py

def close(self) -> None:
    """Close the HTTP client connection."""
    self._client.close()

Basic Usage

from bloomy import Client, ConfigurationError

# Initialize with API key
client = Client(api_key="your-api-key")

# Custom base URL (for testing/staging)
client = Client(
    api_key="your-api-key",
    base_url="https://staging.example.com/api/v1"
)

# Custom timeout (in seconds)
client = Client(api_key="your-api-key", timeout=60.0)

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

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 Client supports context manager protocol for automatic resource cleanup:

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