Goal Operations¶

Operations for managing goals (also known as "rocks") and goal-related data.

API Reference¶

GoalOperations ¶

GoalOperations(client: Client)

Bases: BaseOperations, GoalOperationsMixin

Class to handle all the operations related to goals (also known as "rocks").

Note

This class is already initialized via the client and usable as client.goal.method

Methods:

list –

List all goals for a specific user.
create –

Create a new goal.
delete –

Delete a goal.
update –

Update a goal.
archive –

Archive a rock with the specified goal ID.
restore –

Restore a previously archived goal identified by the provided goal ID.
create_many –

Create multiple goals in a best-effort manner.

Functions¶

list ¶

list(user_id: int | None = None, archived: bool = False) -> list[GoalInfo] | GoalListResponse

List all goals for a specific user.

Parameters:

user_id (int | None, default: None ) –

The ID of the user (default is the initialized user ID)
archived (bool, default: False ) –

Whether to include archived goals (default: False)

Returns:

Either ( list[GoalInfo] | GoalListResponse ) –
list[GoalInfo] | GoalListResponse –
- A list of GoalInfo model instances if archived is false
list[GoalInfo] | GoalListResponse –
- A GoalListResponse model with 'active' and 'archived' lists of GoalInfo instances if archived is true

Examples:

List active goals:

client.goal.list()
# Returns: [GoalInfo(id=1, title='Complete project', ...)]

List both active and archived goals:

client.goal.list(archived=True)
# Returns: GoalListResponse(
#     active=[GoalInfo(id=1, ...)],
#     archived=[ArchivedGoalInfo(id=2, ...)]
# )

create ¶

create(title: str, meeting_id: int, user_id: int | None = None) -> CreatedGoalInfo

Create a new goal.

Parameters:

title (str) –

The title of the new goal
meeting_id (int) –

The ID of the meeting associated with the goal
user_id (int | None, default: None ) –

The ID of the user responsible for the goal (default: initialized user ID)

Returns:

CreatedGoalInfo –

A CreatedGoalInfo model instance representing the newly created goal

Example

client.goal.create(title="New Goal", meeting_id=1)
# Returns: CreatedGoalInfo(id=1, title='New Goal', meeting_id=1, ...)

delete ¶

delete(goal_id: int) -> None

Delete a goal.

Parameters:

goal_id (int) –

The ID of the goal to delete

Example

client.goal.delete(1)

update ¶

update(goal_id: int, title: str | None = None, accountable_user: int | None = None, status: GoalStatus | str | None = None) -> None

Update a goal.

Parameters:

goal_id (int) –

The ID of the goal to update
title (str | None, default: None ) –

The new title of the goal
accountable_user (int | None, default: None ) –

The ID of the user responsible for the goal (default: initialized user ID)
status (GoalStatus | str | None, default: None ) –

The status value. Can be a GoalStatus enum member or string ('on', 'off', or 'complete'). Use GoalStatus.ON_TRACK, GoalStatus.AT_RISK, or GoalStatus.COMPLETE for type safety. Invalid values will raise ValueError via the update payload builder.

Example

from bloomy import GoalStatus

# Using enum (recommended)
client.goal.update(goal_id=1, status=GoalStatus.ON_TRACK)

# Using string
client.goal.update(goal_id=1, status='on')

archive ¶

archive(goal_id: int) -> None

Archive a rock with the specified goal ID.

Parameters:

goal_id (int) –

The ID of the goal/rock to archive

Example

client.goal.archive(123)

restore ¶

restore(goal_id: int) -> None

Restore a previously archived goal identified by the provided goal ID.

Parameters:

goal_id (int) –

The unique identifier of the goal to restore

Example

client.goal.restore(123)

create_many ¶

create_many(goals: list[dict[str, Any]]) -> BulkCreateResult[CreatedGoalInfo]

Create multiple goals in a best-effort manner.

Processes each goal sequentially to avoid rate limiting. Failed operations are captured and returned alongside successful ones.

Parameters:

goals (list[dict[str, Any]]) –

List of dictionaries containing goal data. Each dict should have: - title (required): Title of the goal - meeting_id (required): ID of the associated meeting - user_id (optional): ID of the responsible user (defaults to current user)

Returns:

BulkCreateResult[CreatedGoalInfo] –

BulkCreateResult containing: - successful: List of CreatedGoalInfo instances for successful creations - failed: List of BulkCreateError instances for failed creations

Example

result = client.goal.create_many([
    {"title": "Q1 Revenue Target", "meeting_id": 123},
    {"title": "Product Launch", "meeting_id": 123, "user_id": 456}
])

print(f"Created {len(result.successful)} goals")
for error in result.failed:
    print(f"Failed at index {error.index}: {error.error}")

Async Version¶

The async version AsyncGoalOperations provides the same methods as above, but with async/await support:

AsyncGoalOperations ¶

AsyncGoalOperations(client: AsyncClient)

Async class to handle all operations related to goals (aka "rocks").

Async Usage

All methods have the same parameters and return types as their sync counterparts. Simply add await before each method call. The create_many() method has an additional max_concurrent parameter in the async version for controlling concurrency.

Goal Status Enum¶

The SDK provides a GoalStatus enum for type-safe status updates:

from bloomy import GoalStatus

# Enum values (recommended)
GoalStatus.ON_TRACK     # "on" - Goal is on track
GoalStatus.AT_RISK      # "off" - Goal is at risk
GoalStatus.COMPLETE     # "complete" - Goal is complete

# You can still use strings directly
client.goal.update(goal_id=123, status="on")

Using the Enum

Using GoalStatus enum values is recommended for better type checking and IDE autocomplete support.

Usage Examples¶

SyncAsync

from bloomy import Client, GoalStatus

with Client(api_key="your-api-key") as client:
    # List active goals
    goals = client.goal.list()
    for goal in goals:
        print(f"{goal.title} - Status: {goal.status}")

    # List with archived goals included
    all_goals = client.goal.list(archived=True)
    print(f"Active: {len(all_goals.active)}")
    print(f"Archived: {len(all_goals.archived)}")

    # Create a new goal
    new_goal = client.goal.create(
        title="Increase customer retention by 20%",
        meeting_id=123
    )

    # Update goal status using enum (recommended)
    client.goal.update(
        goal_id=new_goal.id,
        status=GoalStatus.ON_TRACK
    )

    # Or use string directly
    client.goal.update(goal_id=new_goal.id, status="off")  # at risk

    # Archive and restore (both return None)
    client.goal.archive(goal_id=new_goal.id)
    client.goal.restore(goal_id=new_goal.id)

    # Delete a goal (returns None)
    client.goal.delete(goal_id=new_goal.id)

    # Bulk create multiple goals
    goals_data = [
        {"title": "Increase revenue by 20%", "meeting_id": 123},
        {"title": "Launch new product", "meeting_id": 123, "user_id": 456},
    ]
    result = client.goal.create_many(goals_data)

    print(f"Created {len(result.successful)} goals")
    for error in result.failed:
        print(f"Failed at index {error.index}: {error.error}")

import asyncio
from bloomy import AsyncClient, GoalStatus

async def main():
    async with AsyncClient(api_key="your-api-key") as client:
        # List active goals
        goals = await client.goal.list()
        for goal in goals:
            print(f"{goal.title} - Status: {goal.status}")

        # List with archived goals included
        all_goals = await client.goal.list(archived=True)
        print(f"Active: {len(all_goals.active)}")
        print(f"Archived: {len(all_goals.archived)}")

        # Create a new goal
        new_goal = await client.goal.create(
            title="Increase customer retention by 20%",
            meeting_id=123
        )

        # Update goal status using enum (recommended)
        await client.goal.update(
            goal_id=new_goal.id,
            status=GoalStatus.ON_TRACK
        )

        # Or use string directly
        await client.goal.update(goal_id=new_goal.id, status="off")  # at risk

        # Archive and restore (both return None)
        await client.goal.archive(goal_id=new_goal.id)
        await client.goal.restore(goal_id=new_goal.id)

        # Delete a goal (returns None)
        await client.goal.delete(goal_id=new_goal.id)

        # Bulk create with concurrency control
        result = await client.goal.create_many(goals_data, max_concurrent=10)

asyncio.run(main())

Available Methods¶

Method	Description	Parameters
`list()`	Get goals for a user	`user_id`, `archived`
`create()`	Create a new goal	`title`, `meeting_id`, `user_id`
`create_many()`	Create multiple goals in bulk	`goals` (sync); `goals`, `max_concurrent` (async)
`update()`	Update an existing goal	`goal_id`, `title`, `accountable_user`, `status`
`delete()`	Delete a goal	`goal_id`
`archive()`	Archive a goal	`goal_id`
`restore()`	Restore an archived goal	`goal_id`

Status Values

Valid status values are: 'on' (On Track), 'off' (At Risk), or 'complete' (Completed). Use the GoalStatus enum for type-safe updates.

Return Values

The update(), delete(), archive(), and restore() methods return None instead of boolean values.