Skip to main content

Project Boards

Every project has one Kanban board. Use this resource to read the board, manage its columns and labels, and create, change, move, archive and restore its cards.

Access it as client.project_boards on a Strongly client, or the same path on AsyncStrongly with await. All methods exist on both with identical signatures.

Quick start​

from strongly import Strongly

client = Strongly()

# Retrieve one by id
item = client.project_boards.retrieve("<id>")

Methods​

Core​

retrieve​

retrieve(project_id: str) -> Board

Return a project's board: its columns in order, their cards and its labels.

Archived cards are not included; see list_archived_cards.

Parameters

  • project_id (str): The project's id.

Returns

  • Board: The board.

Raises

  • NotFoundError: There is no such project.
  • PermissionDeniedError: You cannot see the project.

Other​

add_card​

add_card(project_id: str, *, column_id: str, title: str, description: str | None = None) -> BoardCard

Add a card at the end of a board column.

Parameters

  • project_id (str): The project's id.
  • column_id (str): The column's id.
  • title (str): The card's title (up to 200 characters).
  • description (str | None, optional): The card's description, in Markdown.

Returns

  • BoardCard: The new card.

Raises

  • NotFoundError: The board has no such column.
  • ValidationError: title is blank.

add_column​

add_column(project_id: str, *, name: str) -> BoardColumnEntry

Add a column at the end of a board.

A new board starts with Ice Box, Backlog, Work In Progress, Ready For Review and Complete. Read the new column's id with retrieve.

Parameters

  • project_id (str): The project's id.
  • name (str): The column's name (up to 60 characters).

Raises

  • ValidationError: name is blank.

archive_card​

archive_card(card_id: str) -> BoardCard

Take a card off its board. It keeps its content and can be restored.

Parameters

  • card_id (str): The card's id.

Raises

  • NotFoundError: There is no such card.

delete_column​

delete_column(project_id: str, column_id: str) -> BoardColumnRemoval

Remove a column from a board.

The cards still in it are archived, not deleted. A board keeps at least one column.

Parameters

  • project_id (str): The project's id.
  • column_id (str): The column's id.

Returns

  • BoardColumnRemoval: How many cards were archived.

Raises

  • NotFoundError: The board has no such column.
  • ValidationError: It is the board's last column.

delete_label​

delete_label(project_id: str, label_id: str) -> None

Delete a board label, taking it off every card (archived ones included).

Parameters

  • project_id (str): The project's id.
  • label_id (str): The label's id.

Raises

  • NotFoundError: The board has no such label.

list_archived_cards​

list_archived_cards(project_id: str, *, search: str | None = None, limit: int | None = None) -> SyncPaginator[ArchivedCard]

List a board's archived cards, newest first, a page at a time as you iterate.

Parameters

  • project_id (str): The project's id.
  • search (str | None, optional): Only cards whose title, description or former column's name contains this text (case insensitive).
  • limit (int | None, optional): The most cards to yield.

Raises

  • PermissionDeniedError: You cannot see the project.

list_members​

list_members(project_id: str) -> list[BoardMember]

List the people on a board, and which of them can be assigned to cards.

Parameters

  • project_id (str): The project's id.

Returns

  • list[BoardMember]: The project's owner and collaborators (assignable), and anyone else a card refers to.

move_card​

move_card(card_id: str, *, to_column_id: str, prev_card_id: str | None = None, next_card_id: str | None = None) -> BoardCard

Move a card to a column.

Without neighbours the card goes to the end of the column. To place it between two cards, name the cards it goes between (both in the target column).

Parameters

  • card_id (str): The card's id.
  • to_column_id (str): The column the card moves to.
  • prev_card_id (str | None, optional): The card that ends up directly above it.
  • next_card_id (str | None, optional): The card that ends up directly below it.

Raises

  • NotFoundError: There is no such card or column.

reorder_columns​

reorder_columns(project_id: str, *, column_ids: Sequence[str]) -> list[BoardColumnEntry]

Set the left-to-right order of a board's columns.

Parameters

  • project_id (str): The project's id.
  • column_ids (Sequence[str]): Every column id on the board, each once, in the new order.

Raises

  • ValidationError: column_ids is not exactly the board's columns.

restore_card​

restore_card(card_id: str, *, to_column_id: str) -> BoardCard

Bring an archived card back, at the end of the column you name.

Parameters

  • card_id (str): The card's id.
  • to_column_id (str): The column the card returns to.

Raises

  • NotFoundError: There is no such card or column.

update_card​

update_card(card_id: str, *, title: str | None = None, description: str | None = None, label_ids: Sequence[str] | None = None, assignee_ids: Sequence[str] | None = None, due_date: datetime | str | None = None, clear_due_date: bool | None = None, due_complete: bool | None = None) -> BoardCard

Change a card. Only the fields you give change.

Parameters

  • card_id (str): The card's id.
  • title (str | None, optional): The card's title.
  • description (str | None, optional): The card's description, in Markdown.
  • label_ids (Sequence[str] | None, optional): The card's labels, replacing the current ones; each must be a label of the board.
  • assignee_ids (Sequence[str] | None, optional): The card's assignees, replacing the current ones; each must be an assignable board member (see list_members).
  • due_date (datetime | str | None, optional): The card's due date, as a datetime or an ISO 8601 string.
  • clear_due_date (bool | None, optional): True removes the card's due date.
  • due_complete (bool | None, optional): Whether the due date has been met.

Raises

  • ValueError: Both due_date and clear_due_date were given.
  • NotFoundError: There is no such card.
  • ValidationError: Nothing to change was given, the title is blank, a label is not the board's or an assignee cannot reach the project.

update_column​

update_column(project_id: str, column_id: str, *, name: str) -> BoardColumnEntry

Rename a board column. Its cards stay where they are.

Parameters

  • project_id (str): The project's id.
  • column_id (str): The column's id.
  • name (str): The column's new name.

Raises

  • NotFoundError: The board has no such column.

upsert_label​

upsert_label(project_id: str, *, name: str, color: str, label_id: str | None = None) -> BoardLabel

Create a board label, or update one by its id; returns the label.

Parameters

  • project_id (str): The project's id.
  • name (str): The label's name (up to 40 characters).
  • color (str): The label's colour, from the board palette: "#6571ff", "#05a34a", "#fbbc06", "#ff3366", "#0dcaf0" or "#7987a1".
  • label_id (str | None, optional): The label to update. Without it a label is created.

Raises

  • ValidationError: color is not in the palette.
  • NotFoundError: The board has no label label_id.