Decks

The governed document. A deck owns its artifact versions, its share state, and its lifecycle status (draft → in review → published → archived). State transitions are field updates — publish a deck by setting `status`, not by calling a verb.

Related guides: Import a deck · Sharing & permissions

Attributes

idstringrequired
objectstringrequired
titlestringrequired
statusstringrequired
current_artifactstring | nullrequired
share_modestringrequired
external_idstring | nullrequired
folderstring | nullrequired
livemodebooleanrequired
metadataobjectrequired
Arbitrary key/value map; merge-on-write (§6).
trashed_attimestamprequired
created_attimestamprequired
updated_attimestamprequired

Endpoints

GET/v1/decks
POST/v1/decks
GET/v1/decks/{id}
PATCH/v1/decks/{id}
DELETE/v1/decks/{id}
GET/v1/decks/{id}/views

The Deck object

{
  "id": "deck_2a9f8c1b",
  "object": "deck",
  "title": "Q3 Board Deck",
  "status": "draft",
  "current_artifact": "art_7c1b…",
  "share_mode": "private",
  "external_id": "q3-board-deck",
  "folder": "fld_7a2c…",
  "livemode": true,
  "metadata": {},
  "trashed_at": null,
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

List decks

GET/v1/decks

Lists decks in the active org, newest first. Filter by `status`; paginate with `cursor`.

Requires an API key (bearer), scoped to the active org.

Query parameters

limitintegeroptionaldefault 201–100
cursorstringoptional
orderstringoptionaldefault "created_at.desc"
Possible values: created_at.desc, created_at.asc
statusstringoptional
trashedstringoptional
List the trash instead of active decks.
Possible values: true, false
folderstringoptional
Filter to a folder id, or `root` for unfiled decks.

Returns

200A page of decks.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza decks list

GET /v1/decks

curl https://api.renza.io/v1/decks \
  -H "Authorization: Bearer $RENZA_API_KEY"

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const page = await renza.decks.list();

Response 200

{
  "object": "list",
  "url": "/v1/decks",
  "data": [
    {
      "id": "deck_2a9f8c1b",
      "object": "deck",
      "title": "Q3 Board Deck",
      "status": "draft",
      "current_artifact": "art_7c1b…",
      "share_mode": "private",
      "external_id": "q3-board-deck",
      "folder": "fld_7a2c…",
      "livemode": true,
      "metadata": {},
      "trashed_at": null,
      "created_at": "2026-06-19T10:30:00.000Z",
      "updated_at": "2026-06-19T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create or upsert a deck

POST/v1/decks

Creates a deck. If `external_id` is provided and already exists in the org, the existing deck is updated instead (200); otherwise a new deck is created (201).

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Body parameters

titlestringoptionalmax 300 chars
statusstringoptional
share_modestringoptional
external_idstringoptionalmax 200 chars
metadataobjectoptional
Arbitrary key/value map; merge-on-write (§6).

Returns

200The upserted (already-existing) deck.
201The newly created deck.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza decks create \
  --title "Q3 Board Deck" \
  --status draft \
  --share-mode private \
  --external-id q3-board-deck

POST /v1/decks

curl https://api.renza.io/v1/decks \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Q3 Board Deck",
  "status": "draft",
  "share_mode": "private",
  "external_id": "q3-board-deck"
}'

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const deck = await renza.decks.create({
  title: "Q3 Board Deck",
  status: "draft",
  share_mode: "private",
  external_id: "q3-board-deck",
});

Response 200

{
  "id": "deck_2a9f8c1b",
  "object": "deck",
  "title": "Q3 Board Deck",
  "status": "draft",
  "current_artifact": "art_7c1b…",
  "share_mode": "private",
  "external_id": "q3-board-deck",
  "folder": "fld_7a2c…",
  "livemode": true,
  "metadata": {},
  "trashed_at": null,
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

Retrieve a deck

GET/v1/decks/{id}

Fetches a deck by Renza id or by `external_id` within the active org.

Requires an API key (bearer), scoped to the active org.

Path parameters

idstringrequired

Returns

200The deck.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza decks get deck_2a9f8c1b

GET /v1/decks/{id}

curl https://api.renza.io/v1/decks/deck_2a9f8c1b \
  -H "Authorization: Bearer $RENZA_API_KEY"

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const deck = await renza.decks.get("deck_2a9f8c1b");

Response 200

{
  "id": "deck_2a9f8c1b",
  "object": "deck",
  "title": "Q3 Board Deck",
  "status": "draft",
  "current_artifact": "art_7c1b…",
  "share_mode": "private",
  "external_id": "q3-board-deck",
  "folder": "fld_7a2c…",
  "livemode": true,
  "metadata": {},
  "trashed_at": null,
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

Update a deck

PATCH/v1/decks/{id}

Partial update — only provided fields change. `metadata` merges (key→value sets, key→null deletes, {} clears all). State transitions are field updates (no verb routes).

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Path parameters

idstringrequired

Body parameters

titlestringoptionalmax 300 chars
statusstringoptional
share_modestringoptional
folderstring | nulloptional
Move to a folder, or null for the root.
current_artifactstringoptional
Roll the deck back to one of its own prior artifact versions.
metadataobjectoptional
Arbitrary key/value map; merge-on-write (§6).
trashedbooleanoptional
Set false to restore a trashed deck.

Returns

200The updated deck.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza decks update deck_2a9f8c1b \
  --title "Q3 Board Deck (final)" \
  --status published \
  --share-mode link \
  --current-artifact art_7c1b…

PATCH /v1/decks/{id}

curl https://api.renza.io/v1/decks/deck_2a9f8c1b \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Q3 Board Deck (final)",
  "status": "published",
  "share_mode": "link",
  "folder": "fld_7a2c…",
  "current_artifact": "art_7c1b…",
  "trashed": false
}'

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const deck = await renza.decks.update("deck_2a9f8c1b", {
  title: "Q3 Board Deck (final)",
  status: "published",
  share_mode: "link",
  folder: "fld_7a2c…",
  current_artifact: "art_7c1b…",
  trashed: false,
});

Response 200

{
  "id": "deck_2a9f8c1b",
  "object": "deck",
  "title": "Q3 Board Deck",
  "status": "draft",
  "current_artifact": "art_7c1b…",
  "share_mode": "private",
  "external_id": "q3-board-deck",
  "folder": "fld_7a2c…",
  "livemode": true,
  "metadata": {},
  "trashed_at": null,
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

Trash or permanently delete a deck

DELETE/v1/decks/{id}

Moves the deck to the trash (soft delete; restore with `PATCH { trashed: false }`). Pass `?permanent=true` to permanently delete an already-trashed deck and its stored content (irreversible).

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Path parameters

idstringrequired

Query parameters

permanentstringoptional
Possible values: true, false

Returns

200The trashed deck, or a deletion confirmation when `?permanent=true`.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza decks trash deck_2a9f8c1b

DELETE /v1/decks/{id}

curl https://api.renza.io/v1/decks/deck_2a9f8c1b \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X DELETE

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const deck = await renza.decks.trash("deck_2a9f8c1b");

Response 200

{
  "id": "deck_2a9f8c1b",
  "object": "deck",
  "title": "Q3 Board Deck",
  "status": "draft",
  "current_artifact": "art_7c1b…",
  "share_mode": "private",
  "external_id": "q3-board-deck",
  "folder": "fld_7a2c…",
  "livemode": true,
  "metadata": {},
  "trashed_at": null,
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

List a deck's viewers

GET/v1/decks/{id}/views

Who opened this deck through its share links (Renza Pro). Link-mode shares return named viewers (names are self-reported); public-mode shares return aggregate counts only. Views are deduplicated per viewer within a 30-minute window.

Requires an API key (bearer), scoped to the active org.

Path parameters

idstringrequired

Returns

200The deck's viewers.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza decks views deck_2a9f8c1b

GET /v1/decks/{id}/views

curl https://api.renza.io/v1/decks/deck_2a9f8c1b/views \
  -H "Authorization: Bearer $RENZA_API_KEY"

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const deck = await renza.decks.views("deck_2a9f8c1b");

Response 200

{
  "object": "deck_views",
  "deck": "deck_2a9f8c1b",
  "viewers": [
    {
      "kind": "anon",
      "name": "Dana Client",
      "first_viewed_at": "2026-06-19T10:30:00.000Z",
      "last_viewed_at": "2026-06-19T10:30:00.000Z",
      "visits": 3
    }
  ],
  "public_views": {
    "total": 42,
    "unique": 17
  },
  "totals": {
    "views": 57,
    "unique_viewers": 21,
    "last_viewed_at": "2026-07-18T14:02:11.000Z"
  },
  "timeline": [
    {
      "date": "2026-07-18",
      "views": 3
    }
  ]
}