---
title: "Bisque Artifact comments"
description: "Read the comment threads people leave on your Artifacts, reply, and resolve them."
canonical: https://bisque.cloud/docs/artifact-comments
---

# Artifact comments

Read the comment threads people leave on your Artifacts, reply, and resolve them.

Page: https://bisque.cloud/docs/artifact-comments

People who open an Artifact you published can leave comment threads on it:
pinned to an element, to a passage, or to the page. When someone mentions the
agent in a thread, the thread is activated and your agent can answer in it,
republish, and mark it resolved. This page is for the agent: how to find the
threads that are waiting on you, read them, reply, resolve, and start a thread
of your own. Both hosts, `https://bisque.today` and `https://bisque.cloud`,
serve every path here, and every path takes `Authorization: Bearer <credential>`
(see [`/auth.md`](/auth.md)). Comments do not exist on public Artifacts.

The same operations exist as MCP tools on the presentations server at `/mcp`:
`list_artifact_threads`, `get_artifact_thread`, `create_artifact_thread`,
`reply_to_artifact_thread`, and `resolve_artifact_thread`. The full HTTP
surface is in [`/openapi.json`](/openapi.json).

## Find the threads waiting on you

Ask for open threads where someone mentioned the agent. That is the whole
work queue.

```bash
curl -s "https://bisque.cloud/v1/artifacts/$ARTIFACT_ID/threads?status=open&activated=true" \
  -H "Authorization: Bearer $BISQUE_API_KEY"
```

```json
{
  "items": [
    {
      "thread_id": "thr_…",
      "status": "open",
      "anchor": {
        "kind": "element",
        "selector": "#revenue-chart",
        "snapshot": { "tag": "div", "text": "Revenue by quarter" },
        "slideId": "s2",
        "slideIndex": 1
      },
      "version_number": 3,
      "preview": "Make this chart larger @Agent",
      "message_count": 2,
      "agent_activated": true,
      "created_by": { "kind": "user", "uid": "…", "name": "Nick" }
    }
  ],
  "next_cursor": null
}
```

`anchor` says what the comment is about. `element` carries the selector and a
text snapshot of the element; `text` carries the quoted passage; `page` is a
general comment, with the slide and time when the Artifact is a presentation.
`version_number` is the Version the person was looking at. Pass `after=` with
an RFC 3339 time to see only threads with activity since your last check, and
`status=all` or `status=resolved` to widen the view.

MCP: `list_artifact_threads` with `{ "artifact_id": "art_…", "activated_only": true }`.

## Read a thread

```bash
curl -s "https://bisque.cloud/v1/artifacts/$ARTIFACT_ID/threads/$THREAD_ID" \
  -H "Authorization: Bearer $BISQUE_API_KEY"
```

The response is the thread plus `messages`, oldest first. Each message has an
`author`, a markdown `body`, `mentions`, `attachments`, and `reactions`. A
mention in a body looks like `@[Nick](mention:uid)`; a mention of the agent is
`@[Agent](mention:agent)`. To view an attached screenshot, fetch
`…/attachments/{attachment_id}` with the same header; it answers with the
image bytes.

MCP: `get_artifact_thread` with `{ "artifact_id", "thread_id" }`.

## Reply

Reply in an activated thread. Say what you changed, then republish, then
resolve. People see the reply as "Agent · via Nick", where Nick is the person
whose credential made the call.

```bash
curl -s -X POST "https://bisque.cloud/v1/artifacts/$ARTIFACT_ID/threads/$THREAD_ID/messages" \
  -H "Authorization: Bearer $BISQUE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"body": "Widened the chart to the full slide in version 4."}'
```

A reply on a thread that is not activated fails with `403 THREAD_NOT_ACTIVATED`.
Mention a person with `@[Name](mention:uid)`; the ids come from
`GET …/mentionables?q=ni`, which lists everyone who can open the Artifact.

MCP: `reply_to_artifact_thread` with `{ "artifact_id", "thread_id", "body" }`.

## Resolve

```bash
curl -s -X PATCH "https://bisque.cloud/v1/artifacts/$ARTIFACT_ID/threads/$THREAD_ID" \
  -H "Authorization: Bearer $BISQUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'
```

Send `{"status": "open"}` to reopen. Resolving after a republish shows people
"Resolved in version N" beside the thread.

MCP: `resolve_artifact_thread` with `{ "artifact_id", "thread_id", "resolved": true }`.

## Start a thread

An agent can leave a comment of its own, for example to ask the owner a
question about a draft. A thread the agent starts is activated from the start,
so you can reply in it and resolve it later. `anchor` is required over HTTP;
use a `page` anchor for a general comment.

```bash
curl -s -X POST "https://bisque.cloud/v1/artifacts/$ARTIFACT_ID/threads" \
  -H "Authorization: Bearer $BISQUE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "anchor": { "kind": "page", "slideId": "s3", "slideIndex": 2, "timeSec": null },
    "body": "@[Nick](mention:uid_nick) the Q3 number on this slide is from the draft sheet. Confirm before I publish?"
  }'
```

MCP: `create_artifact_thread` with `{ "artifact_id", "body", "anchor"? }`;
without an anchor the tool leaves a general comment.

## Where it fits

Comments arrive after you publish with the [API](/docs/api) or the
[MCP server](/docs/mcp). Poll the activated list at the start of a session, or
whenever the owner asks what people said about an Artifact, and close the loop
in the thread: reply, republish, resolve.