From 1432ab841e046d23ce61289299ee45d6c9588a0a Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Wed, 22 Jul 2026 21:58:57 -0700 Subject: [PATCH] Document the cross-card-table card move recipe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Move a card section noted that column_id could be a wormhole id but left the workflow for the reader to assemble. Spell it out: link the card table wormholes endpoints directly and give the two-step recipe for moving a card onto another card table, which may be in another project. Clarify the contract that's easy to get wrong: - Only linked wormholes accept a card; the card table's wormholes array also lists unlinked ones, and moving onto those returns 404 Not Found. - A valid position does not control where a teleported card lands — placement is decided when the asynchronous move completes — but an invalid position still returns 400 Bad Request. - The 204 means the teleport was queued; completion is asynchronous, the response does not expose the destination card's new id, and the original card id returns 404 once the move completes. --- sections/card_table_cards.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/sections/card_table_cards.md b/sections/card_table_cards.md index 1e69df8..e48aacd 100644 --- a/sections/card_table_cards.md +++ b/sections/card_table_cards.md @@ -425,7 +425,14 @@ _Optional parameters_: This endpoint will return `204 No Content` if the move was a success. Returns `400 Bad Request` if `position` is zero, negative, or non-numeric. -The `column_id` may also be the `id` of one of the board's [wormholes](card_tables.md#get-a-card-table). The card is then teleported to the wormhole's destination column on another card table. The teleport is processed asynchronously after the `204 No Content` response, and once it completes the card is filed away in the destination project — subsequent requests for the original card will return `404 Not Found`. +Passing a [wormhole](card_table_wormholes.md)'s `id` as the `column_id` moves the card to **another card table**, including one in another project. A wormhole on the source card table points at a destination column on the other card table; create one with the [card table wormholes](card_table_wormholes.md) endpoints, or reuse a linked one already listed in the card table's `wormholes` array (see [Get a card table](card_tables.md#get-a-card-table)); the wormhole must be linked (`"linked": true`) and its destination reachable by the requester, so moving onto an unlinked or unreachable wormhole returns `404 Not Found`. + +So the recipe is: + +1. Create a wormhole on the source card table (id `2`) pointing at the destination column — `POST /buckets/1/card_tables/2/wormholes.json` with `{"destination_recording_id": }` — and capture the new wormhole's `id` from the `201 Created` response. +2. Move the card (id `2`) onto that wormhole — `POST /card_tables/cards/2/moves.json` with `{"column_id": }`, expecting `204 No Content`. + +The endpoint returns `204 No Content` once the teleport is queued. Completion is asynchronous; the response does not expose the destination card's new recording ID, and the original card ID returns `404 Not Found` after completion. `position` does not control a teleport's destination placement; if supplied, it must still be a positive integer. Placement is determined when the move completes. ###### Example JSON Request