To-do Operations (v2)¶

GraphQL operations for managing to-dos. See the v2 guide for how client.v2 relates to client.v1/client.todo, and for the description ("notes") behavior shared across v2 entities.

API Reference¶

TodoOperations ¶

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

Bases: GraphQLOperations, TodoOperationsMixin

Class to handle v2 (GraphQL) operations related to to-dos.

Methods:

details –

Get details for a to-do.
list –

List to-dos for a meeting or a user.
create –

Create a new to-do.
update –

Update an existing to-do.
complete –

Mark a to-do as complete.
reopen –

Reopen a completed to-do.
archive –

Archive a to-do.
restore –

Restore an archived to-do.

Methods:¶

details ¶

details(todo_id: int) -> Todo

Get details for a to-do.

Parameters:

todo_id (int) –

The ID of the to-do.

Returns:

Todo –

A Todo model instance.

Example

client.v2.todo.details(123)
# Returns: Todo(id=123, title='To-do Title', ...)

list ¶

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

List to-dos for a meeting or a user.

Parameters:

meeting_id (int | None, default: None ) –

The ID of the meeting to list to-dos for.
user_id (int | None, default: None ) –

The ID of the user to list to-dos for. Defaults to the current user when neither meeting_id nor user_id is given.
include_completed (bool, default: False ) –

If True, also include completed to-dos.
include_archived (bool, default: False ) –

If True, also include archived to-dos. Has no effect when listing by user_id: the underlying todos(userId) query excludes archived to-dos unconditionally, server-side.

Returns:

list[Todo] –

A list of Todo model instances, ordered by due date.

Raises:

ValueError –

If both meeting_id and user_id are provided.

Example

client.v2.todo.list(meeting_id=349524)
# Returns: [Todo(id=1, title='To-do 1', ...), ...]

create ¶

create(title: str, meeting_id: int | None = None, user_id: int | None = None, due_date: TimeInput | None = None, notes: str | None = None) -> Todo

Create a new to-do.

Parameters:

title (str) –

The title of the to-do.
meeting_id (int | None, default: None ) –

The ID of the meeting to create the to-do in. Omit for a personal to-do (meetingRecurrenceId is sent as null).
user_id (int | None, default: None ) –

The ID of the to-do owner (defaults to the current user). Ignored by the API for a personal to-do, which is always assigned to the caller.
due_date (TimeInput | None, default: None ) –

The due date. Defaults to 7 days from today at 00:00 UTC, matching the web app's own default.
notes (str | None, default: None ) –

Description text for the to-do.

Returns:

Todo –

The newly created Todo.

Example

client.v2.todo.create("New To-do", meeting_id=349524)
# Returns: Todo(id=456, title='New To-do', ...)

update ¶

update(todo_id: int, *, title: str | None = None, due_date: TimeInput | None = None, user_id: int | None = None, notes: str | None = None) -> Todo

Update an existing to-do.

Parameters:

todo_id (int) –

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

New title for the to-do.
due_date (TimeInput | None, default: None ) –

New due date for the to-do. The due date cannot be cleared, only changed.
user_id (int | None, default: None ) –

New owner for the to-do.
notes (str | None, default: None ) –

New description text for the to-do.

Returns:

Todo –

The updated Todo.

Raises:

ValueError –

If no update fields are provided.

Example

client.v2.todo.update(123, title="New Title")
# Returns: Todo(id=123, title='New Title', ...)

complete ¶

complete(todo_id: int) -> Todo

Mark a to-do as complete.

Parameters:

todo_id (int) –

The ID of the to-do to complete.

Returns:

Todo –

The updated Todo.

reopen ¶

reopen(todo_id: int) -> Todo

Reopen a completed to-do.

Parameters:

todo_id (int) –

The ID of the to-do to reopen.

Returns:

Todo –

The updated Todo.

archive ¶

archive(todo_id: int) -> Todo

Archive a to-do.

Parameters:

todo_id (int) –

The ID of the to-do to archive.

Returns:

Todo –

The updated Todo.

restore ¶

restore(todo_id: int) -> Todo

Restore an archived to-do.

Parameters:

todo_id (int) –

The ID of the to-do to restore.

Returns:

Todo –

The updated Todo.

Async Version¶

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

AsyncTodoOperations ¶

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

Async class to handle v2 (GraphQL) operations related to to-dos.

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:
    # Create a to-do in a meeting (due date defaults to 7 days from today)
    todo = client.v2.todo.create(
        title="Review Q4 metrics",
        meeting_id=123,
        notes="Cross-check against last quarter",
    )

    # Create a personal to-do (no meeting_id)
    personal_todo = client.v2.todo.create(title="Renew certification")

    # Get to-do details
    details = client.v2.todo.details(todo.id)

    # List open to-dos for a meeting
    meeting_todos = client.v2.todo.list(meeting_id=123)

    # Include completed and archived to-dos too
    all_todos = client.v2.todo.list(
        meeting_id=123, include_completed=True, include_archived=True
    )

    # Update title and due date
    updated = client.v2.todo.update(todo.id, title="New title", due_date="2026-01-15")

    # Complete, then reopen
    client.v2.todo.complete(todo.id)
    client.v2.todo.reopen(todo.id)

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

import asyncio
from bloomy import AsyncClient

async def main():
    async with AsyncClient(api_key="your-api-key") as client:
        # Create a to-do in a meeting (due date defaults to 7 days from today)
        todo = await client.v2.todo.create(
            title="Review Q4 metrics",
            meeting_id=123,
            notes="Cross-check against last quarter",
        )

        # List open to-dos for a meeting
        meeting_todos = await client.v2.todo.list(meeting_id=123)

        # Complete, then reopen
        await client.v2.todo.complete(todo.id)
        await client.v2.todo.reopen(todo.id)

asyncio.run(main())

Available Methods¶

Method	Description	Parameters	Returns
`details()`	Get a to-do	`todo_id`	`Todo`
`list()`	List to-dos for a meeting or a user	`meeting_id`, `user_id`, `include_completed`, `include_archived`	`list[Todo]`
`create()`	Create a to-do	`title`, `meeting_id`, `user_id`, `due_date`, `notes`	`Todo`
`update()`	Update a to-do	`todo_id`, `title`, `due_date`, `user_id`, `notes`	`Todo`
`complete()`	Mark a to-do as complete	`todo_id`	`Todo`
`reopen()`	Reopen a completed to-do	`todo_id`	`Todo`
`archive()`	Archive a to-do	`todo_id`	`Todo`
`restore()`	Restore an archived to-do	`todo_id`	`Todo`

Filtering

list() accepts either meeting_id or user_id, not both. Passing both raises ValueError. If neither is given, it defaults to the current user. include_archived has no effect when listing by user_id: the underlying query excludes archived to-dos unconditionally, server-side. Omit meeting_id on create() for a personal to-do — it is always assigned to the caller regardless of user_id.

Update requirements

At least one field must be provided to update(), or it raises ValueError. A due date can be changed but not cleared.