Remote API — API reference¶

Errors¶

CardNotFound ¶

CardNotFound(card_id: int)

Bases: Exception

Raised by mutations when no card has the given id.

RemoteError ¶

Bases: Exception

Base class for errors raised by the remote API.

SchemaMismatch ¶

SchemaMismatch(database: str, expected: int, found: int)

Bases: RemoteError

A database's schema version is not the one this release expects.

Raised instead of migrating: the host pins its own mait-code release, so a newer or older instance needs the host upgrading (or the instance), not a schema change made by the host.

ATTRIBUTE	DESCRIPTION
`database`	The database file name, e.g. `"board.db"`.
`expected`	The schema version this release of mait-code expects.
`found`	The version recorded in the database (`0` if it has none).

TransitionRefused ¶

TransitionRefused(card_id: int, status: str)

Bases: RemoteError

A refine asked for a card or column outside backlog/refined.

ATTRIBUTE	DESCRIPTION
`card_id`	The card the refine targeted.
`status`	The column involved — the card's current one, or the requested target.

Board¶

create_card ¶

create_card(
    data_dir: Path,
    *,
    client: str,
    project: str,
    title: str,
    description: str | None = None,
    priority: str = "medium",
) -> dict

Create a card in backlog, recording client as its creator.

There is no way to create a card anywhere but backlog.

PARAMETER	DESCRIPTION
`data_dir`	The instance's data directory. TYPE: `Path`
`client`	Name of the calling client, stored as `created_by`. TYPE: `str`
`project`	Project the card belongs to. TYPE: `str`
`title`	Card title. TYPE: `str`
`description`	Optional markdown description. TYPE: `str \| None` DEFAULT: `None`
`priority`	`"low"`, `"medium"` or `"high"`. TYPE: `str` DEFAULT: `'medium'`

RETURNS	DESCRIPTION
`dict`	The new card, with its (empty) comments.

RAISES	DESCRIPTION
`ValueError`	If client, project or title is blank, client is too long, or priority is unknown.

get_card ¶

get_card(data_dir: Path, card_id: int) -> dict

Return one card with its comments.

PARAMETER	DESCRIPTION
`data_dir`	The instance's data directory. TYPE: `Path`
`card_id`	The card's id. TYPE: `int`

RETURNS	DESCRIPTION
`dict`	The card dict with a `comments` list, as `show --json` emits it.

RAISES	DESCRIPTION
`CardNotFound`	If no card has that id.

list_cards ¶

list_cards(
    data_dir: Path,
    *,
    project: str | None = None,
    statuses: Iterable[str] | None = None,
    tag: str | None = None,
    search: str | None = None,
) -> list[dict]

Return cards ordered priority-then-oldest.

PARAMETER	DESCRIPTION
`data_dir`	The instance's data directory. TYPE: `Path`
`project`	Restrict to one project, or `None` for every project. TYPE: `str \| None` DEFAULT: `None`
`statuses`	Restrict to these columns; `None` means every column except `archived`. TYPE: `Iterable[str] \| None` DEFAULT: `None`
`tag`	Restrict to cards carrying this tag. TYPE: `str \| None` DEFAULT: `None`
`search`	Case-insensitive substring of the title. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[dict]`	Card dicts in the `mc-tool-board show --json` shape, without
`list[dict]`	comments.

RAISES	DESCRIPTION
`ValueError`	If statuses names an unknown column.

list_projects ¶

list_projects(data_dir: Path) -> list[str]

Return the distinct projects that have cards, sorted.

PARAMETER	DESCRIPTION
`data_dir`	The instance's data directory. TYPE: `Path`

refine_card ¶

refine_card(
    data_dir: Path,
    card_id: int,
    *,
    client: str,
    description: str | None = None,
    acceptance: str | None = None,
    to: str = REFINED,
) -> dict

Edit a card's description/acceptance and place it in backlog or refined.

The card must currently sit in backlog or refined, and to must be one of those two. The change and a comment authored by client recording it are written in one transaction, after re-checking the card's column under the write lock.

PARAMETER	DESCRIPTION
`data_dir`	The instance's data directory. TYPE: `Path`
`card_id`	The card to refine. TYPE: `int`
`client`	Name of the calling client, recorded as the comment author. TYPE: `str`
`description`	New description, or `None` to leave it. TYPE: `str \| None` DEFAULT: `None`
`acceptance`	New acceptance criteria, or `None` to leave them. TYPE: `str \| None` DEFAULT: `None`
`to`	Target column, `"refined"` (default) or `"backlog"`. TYPE: `str` DEFAULT: `REFINED`

RETURNS	DESCRIPTION
`dict`	The card after the change, with its comments.

RAISES	DESCRIPTION
`CardNotFound`	If no card has that id.
`TransitionRefused`	If the card is outside backlog/refined, or to is any other column.
`ValueError`	If client is blank or too long, or the call would change nothing.

Memory¶

search_memories ¶

search_memories(
    data_dir: Path,
    query: str,
    *,
    limit: int = 10,
    entry_type: str | None = None,
    project: str | None = None,
) -> list[dict]

Search memories (keyword plus vector) and rank them.

The same hybrid search and composite ranking as mc-tool-memory search. Superseded and retired entries are excluded.

PARAMETER	DESCRIPTION
`data_dir`	The instance's data directory. TYPE: `Path`
`query`	Search text. TYPE: `str`
`limit`	Maximum number of results. TYPE: `int` DEFAULT: `10`
`entry_type`	Restrict to one entry type (e.g. `"preference"`). TYPE: `str \| None` DEFAULT: `None`
`project`	Project context: global entries plus that project's are searched, and the project's own rank higher. `None` searches every scope. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[dict]`	Memory entry dicts, best first, each with a `score` key.

RAISES	DESCRIPTION
`ValueError`	If query is blank or limit is not positive.

Reminders¶

list_reminders ¶

list_reminders(data_dir: Path) -> list[dict]

Return active (undismissed) reminders, ordered by due time.

PARAMETER	DESCRIPTION
`data_dir`	The instance's data directory. TYPE: `Path`

RETURNS	DESCRIPTION
`list[dict]`	Dicts with `id`, `what`, `due` (ISO 8601 string) and
`list[dict]`	`overdue` (bool).