Cards
A card is a page. Not a page-like object, not a ticket with a description field. It is the same kind of document the rest of the platform is made of, appearing on a board.
Everything that follows from that comes for free, because none of it is reimplemented for cards:
- a body you write in, with the full editor;
- comments and mentions;
- version history, and the trash;
- activity: who created the card, renamed it, changed a field (with the old and the new value) or moved it to another column, under the Activity button in the card's header. A dot on that button, and a dot before the card's title on the board, means someone else changed or commented on the card since you last opened its activity. Your own changes never set it, and opening the activity clears it;
- full-text search;
- workspace fields: the same field defined once for the whole company, not a
custom field invented per board. A field shows on a card once it has a value
or is added with
+. A field is offered for the whole workspace (Settings → Fields), for a collection (its settings) or for one board (View → Fields of this board on the board); tick Always show there and every card it reaches shows it, also empty. The open card groups its fields by where they are offered: From the workspace, From the collection, From the board "…". What a card shows on the board itself is chosen under View → Shown on the board; - events and webhooks.
A card's title is its page's title. A card's body is its page's body. Reading a card as Markdown is reading the page as Markdown:
curl "$BASE/api/v1/workspaces/$WS/pages/$CARD?format=markdown" \
-H "Authorization: Bearer $TOKEN"
There is no card-shaped endpoint for that, and there does not need to be.
Card numbers
Every card has a number, shown as #42 above its title in the open card. The
numbers count up per workspace in the order cards are made, and a card keeps
its number for good: moving it, putting it on a second board or restoring it
from the trash does not change it, and no other card ever gets it.
- A click on the number copies the card's link.
- View on a board has a switch Card number that shows the numbers on all of its cards. It applies to the board, for everyone.
- The address of an open card starts with the number,
…/c/42-rewrite-the-onboarding-mail-<id>. A short…/c/42opens the same card. - Searching for
#42or42puts card 42 first.
Over the API, a card in the grouped read carries number, a page that is a
card carries cardNumber, and GET /api/v1/workspaces/{workspaceId}/cards/42
answers the card's pageId.
One card, several boards
A card can be on more than one board, and it is the same card, not a copy, not a link, not a mirror that syncs. Edit its text on one board and the other board's card already says the same thing, because there is only one of it.
What is not shared is where it sits. Each board holds its own column, lane and position for that card. The same piece of work can be "In review" on the team board and "This quarter" on the roadmap board, and neither placement disturbs the other.
The open card shows every board it is on as its own Status row, with the lane under it where the board has lanes. Each row has the usual actions: click the board's name to open the card there, change the column or the lane, archive the card on that board only, or remove it from that board. Add to board… under the rows puts the card on one more board, of any collection you may edit: pick the board, then its column and lane.
That is the mechanism behind the promise: a card belongs to the work, and boards are views onto the work.
Placing a card
A card gets onto a board in one of two ways:
Create a new one. Give it a title, a column, optionally a lane:
curl -X POST "$BASE/api/v1/workspaces/$WS/boards/$BOARD/cards" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "title": "Rewrite the onboarding mail", "columnId": "…", "laneId": "…" }'
Attach a page that already exists. Send pageId instead of title. This is
how a card reaches a second board, and how an ordinary page becomes a card.
Attaching needs edit on the board and edit on the page, because you are changing
the page's memberships, which is a change to the page.
Position is given by a neighbour: beforeId or afterId. Leave both out and
the card goes to the end of the column, which is also what makes placing the
first card in an empty column work without a special case.
Moving a card
POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards/{pageId}/move
One transactional call, taking the target column, the lane and a neighbour. It changes only this board's placement.
Colliding positions are healed rather than stacked: two clients dropping a card at the same spot at the same moment end up with two distinct positions, not two cards claiming one.
Moving needs edit on the board. See
Permissions. This is deliberate, and it is what lets
a project lead run a board containing work they are not cleared to read.
Archiving a card
In the board, open a card's ⋯ menu and choose Archive. The card
disappears from the board and from the column counts, but it stays on the
board, in its column and lane. A column's ⋯ menu has Archive all cards in
this column, for example for "Done" at the end of a sprint. An open card has
Archive in its own ⋯ menu too; the card closes once it is archived.
The shortcut is ⌘⇧E (Ctrl+Shift+E on Windows and Linux): in an open card it archives that card, on the board it archives the card the keyboard is on, or else the card under the mouse pointer. Both menus show it next to Archive.
If the card is on other boards too, Tecto asks: Only on this board or On all boards. Boards you may not edit keep the card as it is.
While a board has archived cards, its header shows Show archived (N
hidden). Switched on, the archived cards appear paler in their columns, and
their ⋯ menu has Restore from archive, which brings the card back on this
board only. The switch is remembered per board on this device.
Archiving and restoring can be undone: the message after it has Undo, and ⌘Z (Ctrl+Z) does the same. A card archived on all boards comes back on every board it sits on.
Over the API:
POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/archive
{"pageIds": ["{pageId}"]} archive on this board
{"columnId": "{columnId}"} every card in a column
{"pageIds": [...], "allBoards": true}
{"pageIds": [...], "archived": false} restore, this board only
dryRun: true changes nothing and returns how many other boards are involved.
The card read leaves archived cards out and counts them in archivedCount;
?archived=include or ?archived=only returns them.
Taking a card off a board
DELETE /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards/{pageId}
The card leaves the board. The page stays: it is still in the workspace, still searchable, still on any other board it is on.
One refusal is worth knowing: if this board is the page's last home, the
call fails with 409 and the code needs-new-home. Removing the final
membership would leave a page nothing points at, reachable only by search and
in practice lost. Put it on another board first, or trash the page itself if
that is what you meant.
Say where it goes and there is no refusal to work around:
DELETE …/boards/{boardId}/cards/{pageId}?newHomeBoardId={otherBoardId}
The other board has to be one the card is already on, in the same collection. The card is re-homed there and taken off this board in one step, which is what the "move to another board" button does. Prefer it over parking the page somewhere in between: a card that is briefly homed outside any board is a card that is briefly not a card, and things that read the workspace do notice.
Cards without a column
A card can exist on a board with no column. That happens when a row is added to the board's backing database through the generic row API, which knows nothing about columns.
Those cards come back in their own group in the grouped read. They are not an error state; they are the state of "this exists here and nobody has said where". Move them like any other card.
Columns are not fields
A column is not a select option, and a lane is not one either. They live on the board, in its own configuration, and a card's placement is stored per board rather than as a value on the page.
That distinction is why the same card can be in different columns on two boards
at once: a field value is a property of the page and could only ever have one
value. It also means a board's stages never appear as a column in a database
view, and never collide with a Status field somebody defined for the
workspace.
The open card still shows its placement where the fields are: one Status row per board, whose menu moves the card to another column of that board, and on a board with lanes a Lane row under it, whose menu moves the card to another lane (or to the row without a lane) and keeps its column. Either move changes that board only.
Pinning another card or a page
Type /card in a card body and pick a card: it is inserted as a small block
with its icon, title, board, column and the card fields that hold a value. A
click opens the card over its own board.
A page kept outside the boards is pinned by pasting its address into the card body: the link turns into a block with the page's icon and title, and a click opens the page where it lives. As with a project (below), only the link is stored, the words are fetched when the block is drawn, and a page you may not see shows "This card isn't available." The same works the other way: a card's address pasted into such a page shows the card there, with its board and column.
Naming the project a card is part of
A card body takes a project block: type /project, then either paste the
link or id of a project that exists, or type a name and one is made.
The block draws the project's name and links to it. What is stored on the card is only the link (the name is fetched when the block is drawn), so a card whose project you have no access to (or whose product is not active on this workspace) shows a link without a name. Nothing is broken about that; a colleague may well see it.
Two things this deliberately is not:
- not a search. There is no way to browse the projects that exist from here; you paste the address of one you have open, or you make one. The block is a link between two places, not a window into the other.
- not a copy. The project's tasks are not shown on the card and are not editable from it. That may come; today the block names the work and gets you there.
Both halves have to be active on this workspace for the block to work. Making one says so plainly if they are not.
Questions on a card
An agent working on a card can ask a question on it (ask_on_card, see
MCP server). The question shows at the top of the card, under the
title: the question, a line of background if there is one, and one button per
option. The recommended option comes first and says "recommended". If the
agent allowed it, a field below the buttons takes an answer in your own words.
- Answering needs the right to edit the card. Pressing a button or sending a text answers the question; the block then shows "Answered:" with the answer, who gave it and when. An answer cannot be changed; a new decision is a new question.
- An option can move the card. When the agent gave an option a column, the button names it ("→ Done") and answering with it moves the card there, in its lane. That also needs the right to edit the board.
- On the board a card with an open question carries the mark "Question open" until it is answered or withdrawn.
- Without the right to edit you see the question and its options, without buttons.
The agent reads the answer through list_card_questions, get_card or
get_my_work. Webhooks can subscribe to the event "Questions".
Chat with the agent of a card
A card has an agent when one of its person fields names a bot, for example the bot in "Assignee". The first such bot, in the order the fields were made, is the card's agent. On such a card, "Chat with agent" opens a chat below the questions.
- Writing needs the right to edit the card. Enter sends, Shift+Enter starts a new line. A message shows "waiting for the agent" until the agent replies; the reply appears under the agent's name without reloading.
- One message at a time. While your message waits, the field says so; you write again once the agent has answered.
- Some agents answer only people who may steer them. When the bot belongs to an agent the workspace runs and manages itself, writing needs the right to edit where that agent lives, because every message costs that agent's quota. The chat appears only for an agent that answers in a chat and may read the card.
- No answer within an hour marks the message "not answered" with "The agent did not answer."; write again to try once more.
- The agent answers in the card's context. It can also say that it could not answer; the message then shows "not answered" and the reason follows. Write again to try once more.
- The chat stays on the card. Close the card and open it again, and the chat is there. It stays when the agent changes; a card without an agent shows the chat without the field.
- Without the right to edit you read the chat, without the button and without the field.
An agent reads the messages that wait for it through get_my_work and replies
with reply_in_card_chat (see MCP server). Webhooks can subscribe to
the event "Chat with the agent".
What is missing
- Card covers: no image on the front of a card.
- Sorting: a board shows its cards in board order. Filtering by field values works, see Boards.
- Public share links for a board. A card's own page can be shared the ordinary way; the board cannot.
- Comments on the board's body. Comments on cards work.
- Cross-product embedding: no search across products, and a pinned page shows its title, not its content. A card can NAME a project kept elsewhere (above), which is a link and not an embed: nothing of the other side's content is shown here.