Notes

albert.collections.notes.NotesCollection

NotesCollection(*, session: AlbertSession)

Bases: BaseCollection

Manage Notes in the Albert platform.

A Note is a free-text comment attached to another entity (its "parent"), such as a Task, Project, or Inventory Item. Notes are commonly used to record observations, discussion, or context alongside an entity. Users can be mentioned inside a note's text via to_note_mention, and files can be attached to a note through the AttachmentCollection.

This collection is accessed as client.notes.

Example

from albert import Albert
client = Albert()
note = client.notes.create(
    note=Note(parent_id="TASA1", note="Reviewed the results.")
)
print(note.id)

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Attributes:

Name	Type	Description
base_path	str	The base API route for note requests.

Methods:

Name	Description
create	Create a new note attached to a parent entity.
get_by_id	Get a single note by its ID.
update	Update an existing note.
delete	Delete a note by its ID.
get_by_parent_id	List all notes attached to a given parent entity.

Source code in src/albert/collections/notes.py

def __init__(self, *, session: AlbertSession):
    super().__init__(session=session)
    self.base_path = f"/api/{NotesCollection._api_version}/notes"

base_path

base_path = f'/api/{NotesCollection._api_version}/notes'

create

create(*, note: Note) -> Note

Create a new note.

Example

from albert.resources.notes import Note
note = client.notes.create(
    note=Note(parent_id="TASA1", note="Kicked off the experiment.")
)
print(note.id)

Parameters:

Name	Type	Description	Default
note	Note	The note to create. Requires parent_id (the entity the note is attached to) and note (the text content).	required

Returns:

Type	Description
Note	The created note, populated with its assigned ID.

Source code in src/albert/collections/notes.py

def create(self, *, note: Note) -> Note:
    """Create a new note.

    !!! example
        ```python
        from albert.resources.notes import Note
        note = client.notes.create(
            note=Note(parent_id="TASA1", note="Kicked off the experiment.")
        )
        print(note.id)
        ```

    Parameters
    ----------
    note : Note
        The note to create. Requires ``parent_id`` (the entity the note is
        attached to) and ``note`` (the text content).

    Returns
    -------
    Note
        The created note, populated with its assigned ID.
    """
    response = self.session.post(
        self.base_path, json=note.model_dump(by_alias=True, exclude_unset=True, mode="json")
    )
    return Note(**response.json())

get_by_id

get_by_id(*, id: str) -> Note

Get a note by its ID.

Example

note = client.notes.get_by_id(id="...")
note.note
# 'Reviewed the results.'

Parameters:

Name	Type	Description	Default
id	str	The ID of the note to retrieve.	required

Returns:

Type	Description
Note	The fully populated note.

Source code in src/albert/collections/notes.py

def get_by_id(self, *, id: str) -> Note:
    """Get a note by its ID.

    !!! example
        ```python
        note = client.notes.get_by_id(id="...")
        note.note
        # 'Reviewed the results.'
        ```

    Parameters
    ----------
    id : str
        The ID of the note to retrieve.

    Returns
    -------
    Note
        The fully populated note.
    """
    response = self.session.get(f"{self.base_path}/{id}")
    return Note(**response.json())

update

update(*, note: Note) -> Note

Update a note.

Fetch a note (e.g. via get_by_id), modify its fields, then pass it here. The note is matched by its id.

Example

note = client.notes.get_by_id(id="...")
note.note = "Updated comment."
updated = client.notes.update(note=note)

Parameters:

Name	Type	Description	Default
note	Note	The note with updated fields. Must include id.	required

Returns:

Type	Description
Note	The updated note, re-fetched from Albert.

Notes

The following fields can be updated: note, parent_id.

Source code in src/albert/collections/notes.py

def update(self, *, note: Note) -> Note:
    """Update a note.

    Fetch a note (e.g. via [`get_by_id`][albert.collections.notes.NotesCollection.get_by_id]), modify its
    fields, then pass it here. The note is matched by its ``id``.

    !!! example
        ```python
        note = client.notes.get_by_id(id="...")
        note.note = "Updated comment."
        updated = client.notes.update(note=note)
        ```

    Parameters
    ----------
    note : Note
        The note with updated fields. Must include ``id``.

    Returns
    -------
    Note
        The updated note, re-fetched from Albert.

    Notes
    -----
    The following fields can be updated: ``note``, ``parent_id``.
    """
    patch = self._generate_patch_payload(
        existing=self.get_by_id(id=note.id), updated=note, generate_metadata_diff=False
    )
    self.session.patch(
        f"{self.base_path}/{note.id}",
        json=patch.model_dump(mode="json", by_alias=True, exclude_unset=True),
    )
    return self.get_by_id(id=note.id)

delete

delete(*, id: str) -> None

Delete a note by its ID.

Example

client.notes.delete(id="...")

Parameters:

Name	Type	Description	Default
id	str	The ID of the note to delete.	required

Returns:

Type	Description
None

Source code in src/albert/collections/notes.py

def delete(self, *, id: str) -> None:
    """Delete a note by its ID.

    !!! example
        ```python
        client.notes.delete(id="...")
        ```

    Parameters
    ----------
    id : str
        The ID of the note to delete.

    Returns
    -------
    None
    """
    self.session.delete(f"{self.base_path}/{id}")

get_by_parent_id

get_by_parent_id(
    *, parent_id: str, order_by: OrderBy = DESCENDING
) -> list[Note]

List all notes attached to a parent entity.

Example

notes = client.notes.get_by_parent_id(parent_id="TASA1")
for note in notes:
    print(note.note)

Parameters:

Name	Type	Description	Default
parent_id	str	The ID of the parent entity whose notes should be listed (e.g. a Task ID such as "TASA1"). Must include the full entity prefix.	required
order_by	OrderBy	The order to return notes in. Defaults to OrderBy.DESCENDING.	DESCENDING

Returns:

Type	Description
list[Note]	The notes attached to the parent entity.

Source code in src/albert/collections/notes.py

def get_by_parent_id(
    self,
    *,
    parent_id: str,
    order_by: OrderBy = OrderBy.DESCENDING,
) -> list[Note]:
    """List all notes attached to a parent entity.

    !!! example
        ```python
        notes = client.notes.get_by_parent_id(parent_id="TASA1")
        for note in notes:
            print(note.note)
        ```

    Parameters
    ----------
    parent_id : str
        The ID of the parent entity whose notes should be listed (e.g. a Task
        ID such as ``"TASA1"``). Must include the full entity prefix.
    order_by : OrderBy, optional
        The order to return notes in. Defaults to ``OrderBy.DESCENDING``.

    Returns
    -------
    list[Note]
        The notes attached to the parent entity.
    """
    params = {
        "parentId": parent_id,
        "orderBy": order_by,
    }
    response = self.session.get(
        url=self.base_path,
        params=params,
    )
    return [Note(**x) for x in response.json()["Items"]]