API pipeline: Collect cards in workspaces

Index: API pipelines — index

Goal: collect cards of any type in workspaces: create one, add, remove and reorder cards, find which of your workspaces hold a card.

Steps

1. Create.

POST /v0/my/workspaces
Idempotency-Key: ws-trip-1
{"title": "Trip ideas", "language": "en"}
→ {"nonce": "470000000000000051", "card_type": "workspace", "visibility": "Private", …}

Optional: content, handle, visibility + permissions + publicity, rubrics, location, workspaces (place it inside other workspaces you can write). Without them it starts Private.

2. Add a card.

POST /v0/my/workspaces/470000000000000051/470000000000000001
{}
→ 204

The card must be one you can read; it goes to the end, or to position {"seqnum": 0}. Adding the same card again changes nothing.

3. Reorder: PATCH /v0/my/workspaces/{ws}/{card} {"seqnum": 2} → 204.

4. Remove: DELETE /v0/my/workspaces/{ws}/{card} → 204.

5. Read it.

GET /v0/graph/workspaces/470000000000000051?contained_limit=50&contained_offset=0
→ {"nonce": "…", "i18n": […], "contained": [{tile}, …], "contained_next_offset": 50, …}

Page with contained_next_offset until it is absent (contained_limit 1–200). GET /v0/my/workspaces/{nonce} returns the same for your own workspaces.

6. Find workspaces: GET /v0/my/workspaces?q=trip&limit=20 (title match); containing=<card nonce>[,<nonce>…] puts your workspaces that already hold those cards first; scope=owned|granted|all.

7. Edit or delete the workspace: PATCH /v0/my/workspaces/{nonce} (title, content, handle, visibility…), DELETE /v0/my/workspaces/{nonce}. Deleting a workspace does not delete the cards in it.

Behind

• A workspace can hold cards of every type, including other workspaces; it cannot hold itself or one of its own ancestors.
• Sharing: putting someone else's card into your workspace shares nothing of it; people you share the workspace with reach only the cards whose owners shared them. Cabi.Chat Graph — Card Policies
• A card in any of your workspaces counts as saved by you (the star; saved_by_viewer on the card).

Rules

• 400 a workspace cannot contain itself, would create a cycle, card must be a numeric nonce.
• 404: the workspace is not yours to write, or the card is unknown or not readable for you.
• 400 on a history workspace: version workspaces are written only by the version history.

API surface