Goal Operations (v2)¶

GraphQL operations for managing goals (rocks). See the v2 guide for how client.v2 relates to client.v1/client.goal, and for the description ("notes") behavior shared across v2 entities. For working with a goal's milestones individually, see Milestone Operations.

API Reference¶

GoalOperations ¶

GoalOperations(client: Any, graphql_url: str, user_id_cache: UserIdCache | None = None)

Bases: GraphQLOperations, GoalOperationsMixin

Class to handle v2 (GraphQL) operations related to goals (rocks).

Methods:

list –

List goals for a meeting or a user.
details –

Get details for a goal, including its milestones.
create –

Create a new goal.
update –

Update an existing goal.
archive –

Archive a goal.
restore –

Restore an archived goal.

Methods:¶

list ¶

list(meeting_id: int | None = None, user_id: int | None = None, *, include_archived: bool = False) -> list[Goal]

List goals for a meeting or a user.

Parameters:

meeting_id (int | None, default: None ) –

List goals attached to this meeting.
user_id (int | None, default: None ) –

List goals owned by this user (defaults to the current user when both meeting_id and user_id are omitted).
include_archived (bool, default: False ) –

If True, also include archived goals.

Returns:

list[Goal] –

A list of Goal model instances (each including its
list[Goal] –

milestones), ordered by due date.

Raises:

ValueError –

If both meeting_id and user_id are provided.

Example

client.v2.goal.list(349524)
# Returns: [Goal(id=1, title='Ship v2', ...), ...]

details ¶

details(goal_id: int) -> Goal

Get details for a goal, including its milestones.

Parameters:

goal_id (int) –

The ID of the goal.

Returns:

Goal –

A Goal model instance.

Example

client.v2.goal.details(5265048)
# Returns: Goal(id=5265048, title='Ship v2', ...)

create ¶

create(meeting_id: int, title: str, user_id: int | None = None, due_date: TimeInput | None = None, status: GoalStatus | str = ON_TRACK, notes: str | None = None, milestones: list[dict[str, Any] | tuple[Any, ...]] | None = None) -> Goal

Create a new goal.

Parameters:

meeting_id (int) –

The ID of the meeting to attach the goal to.
title (str) –

The title of the goal.
user_id (int | None, default: None ) –

The ID of the goal owner (defaults to the current user).
due_date (TimeInput | None, default: None ) –

The due date, as a datetime, date, or unix timestamp (seconds). Defaults to 90 days from today (00:00 UTC).
status (GoalStatus | str, default: ON_TRACK ) –

The initial status.
notes (str | None, default: None ) –

Description text for the goal.
milestones (list[dict[str, Any] | tuple[Any, ...]] | None, default: None ) –

Milestones to create alongside the goal, each either {"title": ..., "due_date": ..., "completed": ...} (completed optional, defaults to False) or a (title, due_date) / (title, due_date, completed) tuple.

Returns:

Goal –

The newly created Goal.

Example

client.v2.goal.create(349524, "Ship v2", notes="Launch details")
# Returns: Goal(id=456, title='Ship v2', ...)

update ¶

update(goal_id: int, *, title: str | None = None, status: GoalStatus | str | None = None, due_date: TimeInput | None = None, user_id: int | None = None, notes: str | None = None) -> Goal

Update an existing goal.

Parameters:

goal_id (int) –

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

New title for the goal.
status (GoalStatus | str | None, default: None ) –

New status for the goal.
due_date (TimeInput | None, default: None ) –

New due date, as a datetime, date, or unix timestamp (seconds).
user_id (int | None, default: None ) –

New owner for the goal.
notes (str | None, default: None ) –

New description text for the goal.

Returns:

Goal –

The updated Goal.

Raises:

ValueError –

If no update fields are provided.

Example

client.v2.goal.update(5265048, title="New title")
# Returns: Goal(id=5265048, title='New title', ...)

archive ¶

archive(goal_id: int) -> Goal

Archive a goal.

Note

Verified live: EditGoal{archived: true} can report success without archiving the goal, because the server discards the archive step's exceptions. This re-reads the goal and raises GraphQLError if it is still not archived.

Parameters:

goal_id (int) –

The ID of the goal to archive.

Returns:

Goal –

The updated Goal.

Raises:

GraphQLError –

If the goal is still not archived after the edit.

restore ¶

restore(goal_id: int) -> Goal

Restore an archived goal.

Note

Verified live against production: EditGoal{archived: false} reliably un-archives the goal and re-attaches the meeting links that were detached within ±3 minutes of the archive.

Parameters:

goal_id (int) –

The ID of the goal to restore.

Returns:

Goal –

The updated Goal.

Async Version¶

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

AsyncGoalOperations ¶

AsyncGoalOperations(client: Any, graphql_url: str, user_id_cache: UserIdCache | None = None)

Async class to handle v2 (GraphQL) operations related to goals (rocks).

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 datetime import date
from bloomy import Client
from bloomy.v2.models import GoalStatus

with Client(api_key="your-api-key") as client:
    # Create a goal (due date defaults to 90 days from today)
    goal = client.v2.goal.create(
        meeting_id=123,
        title="Ship v2",
        notes="Launch details",
    )

    # Create a goal with milestones in the same call
    goal_with_milestones = client.v2.goal.create(
        meeting_id=123,
        title="Ship v2",
        milestones=[
            {"title": "Draft spec", "due_date": date(2026, 1, 1)},
            ("Beta release", date(2026, 2, 1)),
        ],
    )

    # Get goal details, including milestones
    details = client.v2.goal.details(goal.id)
    for milestone in details.milestones:
        print(f"{milestone.title}: completed={milestone.completed}")

    # List goals for a meeting
    meeting_goals = client.v2.goal.list(meeting_id=123)

    # List goals for the current user, including archived ones
    my_goals = client.v2.goal.list(include_archived=True)

    # Update status using the v2 enum (ON_TRACK / OFF_TRACK / COMPLETED)
    updated = client.v2.goal.update(goal.id, status=GoalStatus.OFF_TRACK)

    # Archive, then restore
    client.v2.goal.archive(goal.id)
    client.v2.goal.restore(goal.id)

import asyncio
from bloomy import AsyncClient
from bloomy.v2.models import GoalStatus

async def main():
    async with AsyncClient(api_key="your-api-key") as client:
        # Create a goal (due date defaults to 90 days from today)
        goal = await client.v2.goal.create(
            meeting_id=123,
            title="Ship v2",
            notes="Launch details",
        )

        # Get goal details, including milestones
        details = await client.v2.goal.details(goal.id)

        # Update status using the v2 enum (ON_TRACK / OFF_TRACK / COMPLETED)
        updated = await client.v2.goal.update(goal.id, status=GoalStatus.OFF_TRACK)

        # Archive, then restore
        await client.v2.goal.archive(goal.id)
        await client.v2.goal.restore(goal.id)

asyncio.run(main())

Available Methods¶

Method	Description	Parameters	Returns
`list()`	List goals for a meeting or a user	`meeting_id`, `user_id`, `include_archived`	`list[Goal]`
`details()`	Get a goal, including its milestones	`goal_id`	`Goal`
`create()`	Create a goal, optionally with milestones	`meeting_id`, `title`, `user_id`, `due_date`, `status`, `notes`, `milestones`	`Goal`
`update()`	Update a goal	`goal_id`, `title`, `status`, `due_date`, `user_id`, `notes`	`Goal`
`archive()`	Archive a goal	`goal_id`	`Goal`
`restore()`	Restore an archived goal	`goal_id`	`Goal`

GoalStatus is different from the v1 enum

bloomy.v2.models.GoalStatus (ON_TRACK / OFF_TRACK / COMPLETED) is a distinct enum from bloomy.GoalStatus (v1's on / off / complete). Import the v2 one from bloomy.v2.models when working with client.v2.goal.

milestones= on create()

Each item is either {"title": ..., "due_date": ..., "completed": ...} (completed optional, defaults to False) or a (title, due_date) / (title, due_date, completed) tuple. To add milestones to an existing goal afterwards, use client.v2.milestone.create() instead.

archive() can raise GraphQLError

The underlying EditGoal(archived: true) mutation can report success without archiving anything, due to a server-side bug. archive() re-reads the goal after the edit and raises GraphQLError if it is still not archived, so a caught exception here reliably means the archive did not take effect — it is safe to retry.

Update requirements

At least one field must be provided to update(), or it raises ValueError.