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). 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.

Find the threads waiting on you

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

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

{
  "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

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.

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

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.

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 or the MCP server. 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.