Shares

API reference

Link access to a deck. A share mints a token URL; anyone with the link gets the deck's public surface. For person-level access with roles, use grants instead.

Related guides: Sharing & permissions

Attributes

idstringrequired
objectstringrequired
tokenstringrequired
deckstringrequired
modestringrequired
Possible values: link, public
urlstringrequired
expires_attimestamprequired
revoked_attimestamprequired
created_attimestamprequired

Endpoints

GET/v1/shares
POST/v1/shares
DELETE/v1/shares/{id}
GET/v1/public/shares/{token}

The Share object

{
  "id": "shr_7a2c…",
  "object": "share",
  "token": "X3k9...x",
  "deck": "deck_2a9f8c1b",
  "mode": "link",
  "url": "https://renza.io/v/X3k9…x",
  "expires_at": null,
  "revoked_at": null,
  "created_at": "2026-06-19T10:30:00.000Z"
}

List a deck's shares

GET/v1/shares

Lists the share tokens for a deck (newest first), including revoked ones.

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

Query parameters

deckstringrequired

Returns

200The deck's shares.

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

Terminal

renza shares list <deck>

GET /v1/shares

curl https://api.renza.io/v1/shares \
  -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.shares.list("deck_2a9f8c1b");

Response 200

{
  "object": "list",
  "url": "/v1/decks",
  "data": [
    {
      "id": "shr_7a2c…",
      "object": "share",
      "token": "X3k9...x",
      "deck": "deck_2a9f8c1b",
      "mode": "link",
      "url": "https://renza.io/v/X3k9…x",
      "expires_at": null,
      "revoked_at": null,
      "created_at": "2026-06-19T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Mints a share token for a deck and sets the deck's share mode. Anyone with the resulting link can view — no account needed. `link` mode is for review: viewers give a name, and comments and presence are on. `public` mode is a plain hosted deck: no comments, no presence, no name or passcode prompts.

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

Body parameters

deckstringrequired
Deck id or external_id.
modestringoptional
Possible values: link, public
expires_in_daysintegeroptional1–365
Link stops resolving after this many days (Renza Pro).
passwordstringoptionalmax 72 chars
Viewers must enter this passcode before the deck serves (Renza Pro). Stored hashed. Link-mode shares only — a public share never takes one.

Returns

201The created share.

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

Terminal

renza shares create deck_2a9f8c1b --mode link

POST /v1/shares

curl https://api.renza.io/v1/shares \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "deck": "deck_2a9f8c1b",
  "mode": "link",
  "expires_in_days": 30
}'

TypeScript

import { createRenzaClient } from "renza-sdk";

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

const share = await renza.shares.create({
  deck: "deck_2a9f8c1b",
  mode: "link",
  expires_in_days: 30,
});

Response 201

{
  "id": "shr_7a2c…",
  "object": "share",
  "token": "X3k9...x",
  "deck": "deck_2a9f8c1b",
  "mode": "link",
  "url": "https://renza.io/v/X3k9…x",
  "expires_at": null,
  "revoked_at": null,
  "created_at": "2026-06-19T10:30:00.000Z"
}

Revoke a share

DELETE/v1/shares/{id}

Revokes a share token; its link 404s immediately. Other shares of the deck are unaffected.

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

Path parameters

idstringrequired

Returns

200The revoked share.

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

Terminal

renza shares revoke shr_7a2c…

DELETE /v1/shares/{id}

curl https://api.renza.io/v1/shares/shr_7a2c… \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X DELETE

TypeScript

import { createRenzaClient } from "renza-sdk";

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

const share = await renza.shares.revoke("shr_7a2c…");

Response 200

{
  "id": "shr_7a2c…",
  "object": "share",
  "token": "X3k9...x",
  "deck": "deck_2a9f8c1b",
  "mode": "link",
  "url": "https://renza.io/v/X3k9…x",
  "expires_at": null,
  "revoked_at": null,
  "created_at": "2026-06-19T10:30:00.000Z"
}

Resolve a share token (public)

GET/v1/public/shares/{token}

Public, unauthenticated: resolve a share token to public-safe deck info. Returns 404 for unknown/revoked/expired tokens (no oracle). The artifact itself is served only from the content origin.

Public — no authentication required.

Path parameters

tokenstringrequired

Returns

200The resolved share.

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

Terminal

renza shares resolve X3k9…x

GET /v1/public/shares/{token}

curl https://api.renza.io/v1/public/shares/X3k9…x

TypeScript

import { createRenzaClient } from "renza-sdk";

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

const share = await renza.shares.resolve("X3k9…x");

Response 200

{
  "object": "public_share",
  "mode": "link",
  "protected": false,
  "deck": {
    "id": "deck_2a9f8c1b",
    "title": "Q3 Board Deck"
  }
}

Attributes

List a deck's shares

Query parameters

Returns

Share a deck

Body parameters

Returns

Revoke a share

Path parameters

Returns

Resolve a share token (public)

Path parameters

Returns