Goal Operations¶

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

API Reference¶

GoalOperations ¶

GoalOperations(client: Client)

Bases: BaseOperations

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) -> bool

Delete a goal.

Parameters:

goal_id (int) –

The ID of the goal to delete

Returns:

bool –

True if deletion was successful

Example

client.goal.delete(1)
# Returns: True

update ¶

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

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 (str | None, default: None ) –

The status value ('on', 'off', or 'complete')

Returns:

bool –

True if the update was successful

Raises:

ValueError –

If an invalid status value is provided

Example

client.goal.update(goal_id=1, title="Updated Goal", status='on')
# Returns: True

archive ¶

archive(goal_id: int) -> bool

Archive a rock with the specified goal ID.

Parameters:

goal_id (int) –

The ID of the goal/rock to archive

Returns:

bool –

True if the archival was successful, False otherwise

Example

goals.archive(123)
# Returns: True

restore ¶

restore(goal_id: int) -> bool

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

Parameters:

goal_id (int) –

The unique identifier of the goal to restore

Returns:

bool –

True if the restore operation was successful, False otherwise

Example

goals.restore(123)
# Returns: True

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

Raises:

ValueError –

When required parameters are missing in goal data

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").

Initialize the async goal operations.

Parameters:

client (AsyncClient) –

The async HTTP client to use for API requests.

Async Usage

All methods have the same parameters and return types as their sync counterparts. Simply add await before each method call.

Usage Examples¶

SyncAsync

from bloomy import Client

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
    client.goal.update(
        goal_id=new_goal.id,
        status="on"  # on track
    )

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

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

import asyncio
from bloomy import AsyncClient

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
        await client.goal.update(
            goal_id=new_goal.id,
            status="on"  # on track
        )

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

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

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`
`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)