Workstreams and identifiers

A workstream is a workspace-level namespace for card identifiers — independent of boards and columns. Every workspace is provisioned with a default workstream (prefix: "MAIN", is_default: true) so every existing card already has an identifier with no setup required. Create additional workstreams to give different initiatives their own identifier series, for example ENG-142 for engineering and SUP-8 for support, regardless of which board or column the card lives in.

Endpoints

Operation	Endpoint
List the workspace's workstreams	GET /workstreams
Create a workstream	POST /workstreams
Read a workstream	GET /workstreams/{workstream_id}
Rename or redescribe a workstream	PATCH /workstreams/{workstream_id}
Archive a workstream	POST /workstreams/{workstream_id}/archive
Resolve a card by identifier (current or alias)	GET /cards/by-identifier/{identifier}
List a card's identifier history	GET /cards/{card_id}/identifiers
Transfer a card to another workstream	POST /cards/{card_id}/workstream

Creating a workstream is a normal idempotent POST — see Idempotency. Renaming is guarded by If-Match; archiving requires both Idempotency-Key and If-Match — see Optimistic concurrency.

Prefix rules

A workstream's prefix is chosen at creation and never changes:

• 2 to 10 characters, starting with a letter, the rest letters or digits (^[A-Za-z][A-Za-z0-9]{1,9}$ on the way in).
• Accepted case-insensitively but stored and returned uppercase (eng and ENG create the same prefix).
• Unique within the workspace, and immutable once used: PATCH /workstreams/{workstream_id} can change name and description only — the prefix is not one of the patchable fields.
• Never reused. A prefix that has ever been assigned — including one belonging to an archived workstream — cannot be claimed by a new workstream. This is what keeps every identifier permanently and unambiguously resolvable.

Identifiers are server-issued and sequential

When a card is created (or transferred — see below), the server assigns it the next sequential number in its workstream and stores the identifier as PREFIX-N (ENG-1, ENG-2, ...). You never choose or write a number yourself. CardView carries the current identifier alongside a workstream summary (id, name, prefix).

Cards are filed into the default workstream unless you say otherwise: POST /columns/{column_id}/cards accepts an optional workstream_id.

Transfers mint a new identifier and keep the old one as an alias

POST /cards/{card_id}/workstream moves a card to a different, active workstream of the same workspace. Like moveCard, it is a versioned write: it requires both an Idempotency-Key and an If-Match with the card's current version.

The transfer allocates a new identifier in the target workstream's sequence. The identifier the card had before the transfer does not disappear — it becomes a permanent alias, forever resolvable to the card, and never reassigned to anything else. GET /cards/{card_id}/identifiers returns the full history, oldest first: each entry's is_current flag marks the one identifier currently active, and superseded_at records when an alias stopped being current.

A card can be transferred more than once; every prior identifier remains a permanent alias.

Resolving an identifier

GET /cards/by-identifier/{identifier} takes any identifier the workspace has ever issued — current or alias — matched exactly, case-insensitively, and returns:

• card — the full, actor-visible card;
• resolved_identifier — the identifier you supplied, echoed back;
• is_alias — true when what you supplied is a superseded alias rather than the card's current identifier;
• current_identifier — the identifier to use going forward.

Use this to keep a stored reference (a link in a document, a ticket number in another system) working forever, while nudging callers toward the current identifier when is_alias comes back true.

Board moves never change identity

Moving a card between columns or boards (POST /cards/{card_id}/move, including a cross-board move — see Move cards safely) never touches its identifier, its workstream, or its alias history. Identity lives in the workstream, not in board placement; only an explicit workstream transfer changes it.

For the end-to-end flow — creating a workstream, filing a card into it, transferring it, and resolving an alias — see Organize work with workstreams.