Comments

The review loop. Comments anchor to a deck, slide, and element, survive version changes, thread via `parent`, and resolve via a `PATCH { resolved: true }` — fully agent-addressable.

Related guides: Comments & versions

Attributes

idstringrequired
objectstringrequired
deckstringrequired
artifactstring | nullrequired
parentstring | nullrequired
The thread root; null for a root.
authorstring | nullrequired
slide_indexnumber | nullrequired
anchorobject | object | nullrequired
bodystringrequired
resolvedbooleanrequired
resolved_attimestamprequired
resolved_bystring | nullrequired
external_idstring | nullrequired
livemodebooleanrequired
metadataobjectrequired
Arbitrary key/value map; merge-on-write (§6).
created_attimestamprequired
updated_attimestamprequired

Endpoints

GET/v1/comments
POST/v1/comments
GET/v1/comments/{id}
PATCH/v1/comments/{id}
DELETE/v1/comments/{id}

The Comment object

{
  "id": "com_5d2a…",
  "object": "comment",
  "deck": "deck_2a9f…",
  "artifact": "art_7c1b…",
  "parent": null,
  "author": "usr_1a2b…",
  "slide_index": 2,
  "anchor": {
    "kind": "element",
    "ref": "h2#title",
    "refKind": "id",
    "x": 0.5,
    "y": 0.5
  },
  "body": "This number looks off — should it be Q3?",
  "resolved": false,
  "resolved_at": "2026-06-19T10:30:00.000Z",
  "resolved_by": null,
  "external_id": "review-note-1",
  "livemode": true,
  "metadata": {},
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

List comments

GET/v1/comments

Lists comments in the active org, newest first. Filter by `deck`, `slide_index`, `resolved`, or `parent`.

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
deckstringoptional
slide_indexinteger | nulloptional
resolvedstringoptional
Only open or only resolved.
Possible values: true, false
parentstringoptional
Replies under this thread root.

Returns

200A page of comments.

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

Terminal

renza comments list

GET /v1/comments

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

Response 200

{
  "object": "list",
  "url": "/v1/decks",
  "data": [
    {
      "id": "com_5d2a…",
      "object": "comment",
      "deck": "deck_2a9f…",
      "artifact": "art_7c1b…",
      "parent": null,
      "author": "usr_1a2b…",
      "slide_index": 2,
      "anchor": {
        "kind": "element",
        "ref": "h2#title",
        "refKind": "id",
        "x": 0.5,
        "y": 0.5
      },
      "body": "This number looks off — should it be Q3?",
      "resolved": false,
      "resolved_at": "2026-06-19T10:30:00.000Z",
      "resolved_by": null,
      "external_id": "review-note-1",
      "livemode": true,
      "metadata": {},
      "created_at": "2026-06-19T10:30:00.000Z",
      "updated_at": "2026-06-19T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a comment or reply

POST/v1/comments

Creates a thread root (`deck` + `slide_index` + `anchor`) or a reply (`parent`). If `external_id` is provided and already exists in the org, the existing comment's body is updated instead (200).

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

Body parameters

bodystringrequiredmax 5000 chars
parentstringoptional
Reply to this comment.
deckstringoptional
artifactstringoptional
Version the anchor was made on.
slide_indexintegeroptionalmin 0
anchorobject | object | nulloptional
external_idstringoptionalmax 200 chars
metadataobjectoptional
Arbitrary key/value map; merge-on-write (§6).

Returns

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

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

Terminal

renza comments create deck_2a9f… \
  --body "This number looks off." \
  --slide-index 2 \
  --external-id review-note-1

POST /v1/comments

curl https://api.renza.io/v1/comments \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "body": "This number looks off.",
  "parent": "com_5d2a…",
  "deck": "deck_2a9f…",
  "artifact": "art_7c1b…",
  "slide_index": 2,
  "anchor": {
    "kind": "element",
    "ref": "h2#title",
    "refKind": "id",
    "x": 0.5,
    "y": 0.5
  },
  "external_id": "review-note-1"
}'

TypeScript

import { createRenzaClient } from "renza-sdk";

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

const comment = await renza.comments.create({
  body: "This number looks off.",
  parent: "com_5d2a…",
  deck: "deck_2a9f…",
  artifact: "art_7c1b…",
  slide_index: 2,
  anchor: {
    kind: "element",
    ref: "h2#title",
    refKind: "id",
    x: 0.5,
    y: 0.5,
  },
  external_id: "review-note-1",
});

Response 200

{
  "id": "com_5d2a…",
  "object": "comment",
  "deck": "deck_2a9f…",
  "artifact": "art_7c1b…",
  "parent": null,
  "author": "usr_1a2b…",
  "slide_index": 2,
  "anchor": {
    "kind": "element",
    "ref": "h2#title",
    "refKind": "id",
    "x": 0.5,
    "y": 0.5
  },
  "body": "This number looks off — should it be Q3?",
  "resolved": false,
  "resolved_at": "2026-06-19T10:30:00.000Z",
  "resolved_by": null,
  "external_id": "review-note-1",
  "livemode": true,
  "metadata": {},
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

Retrieve a comment

GET/v1/comments/{id}

Fetches a comment 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 comment.

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

Terminal

renza comments get com_5d2a…

GET /v1/comments/{id}

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

TypeScript

import { createRenzaClient } from "renza-sdk";

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

const comment = await renza.comments.get("com_5d2a…");

Response 200

{
  "id": "com_5d2a…",
  "object": "comment",
  "deck": "deck_2a9f…",
  "artifact": "art_7c1b…",
  "parent": null,
  "author": "usr_1a2b…",
  "slide_index": 2,
  "anchor": {
    "kind": "element",
    "ref": "h2#title",
    "refKind": "id",
    "x": 0.5,
    "y": 0.5
  },
  "body": "This number looks off — should it be Q3?",
  "resolved": false,
  "resolved_at": "2026-06-19T10:30:00.000Z",
  "resolved_by": null,
  "external_id": "review-note-1",
  "livemode": true,
  "metadata": {},
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

Update a comment

PATCH/v1/comments/{id}

Partial update — only provided fields change. `resolved` resolves/reopens the thread (a field update, not a verb route). `metadata` merges (key→value sets, key→null deletes, {} clears all).

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

Path parameters

idstringrequired

Body parameters

bodystringoptionalmax 5000 chars
resolvedbooleanoptional
Resolve (true) or reopen (false).
metadataobjectoptional
Arbitrary key/value map; merge-on-write (§6).

Returns

200The updated comment.

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

Terminal

renza comments update com_5d2a…

PATCH /v1/comments/{id}

curl https://api.renza.io/v1/comments/com_5d2a… \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
  "resolved": true
}'

TypeScript

import { createRenzaClient } from "renza-sdk";

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

const comment = await renza.comments.update("com_5d2a…", {
  resolved: true,
});

Response 200

{
  "id": "com_5d2a…",
  "object": "comment",
  "deck": "deck_2a9f…",
  "artifact": "art_7c1b…",
  "parent": null,
  "author": "usr_1a2b…",
  "slide_index": 2,
  "anchor": {
    "kind": "element",
    "ref": "h2#title",
    "refKind": "id",
    "x": 0.5,
    "y": 0.5
  },
  "body": "This number looks off — should it be Q3?",
  "resolved": false,
  "resolved_at": "2026-06-19T10:30:00.000Z",
  "resolved_by": null,
  "external_id": "review-note-1",
  "livemode": true,
  "metadata": {},
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

Delete a comment

DELETE/v1/comments/{id}

Permanently deletes a comment (irreversible). Deleting a thread root also deletes its replies.

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

Path parameters

idstringrequired

Returns

200The deletion confirmation.

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

Terminal

renza comments delete com_5d2a…

DELETE /v1/comments/{id}

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

TypeScript

import { createRenzaClient } from "renza-sdk";

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

const comment = await renza.comments.delete("com_5d2a…");

Response 200

{
  "object": "comment",
  "deleted": true
}