canonical: https://jentic.com/apis/sanity.io/sanity-comments-api

# Sanity Collaboration API

The Sanity Collaboration API creates, edits, resolves, and deletes the comments and reactions that editors leave on Sanity documents and Canvas documents. Comments can target a whole document or a specific field, optionally anchored to a span of Portable Text, and replies join the parent comment's thread. Reads run as GROQ queries against the comments of a resource, and a listen operation streams comment changes as server-sent events. Dataset comments use the project host, Canvas comments use api.sanity.io, and the vX version is unstable and can change without notice.

## For AI agents

Query, create, reply to, resolve, and delete comments on Sanity documents and Canvas, add or remove emoji reactions, and stream comment changes.

## Scope

Does not edit document content, publish changes, or send email notifications. Use for querying, creating, updating, and deleting comments and reactions on Sanity documents and Canvas only.

## Capabilities

- Query a resource's comments with GROQ through GET or POST `/vX/collaboration/comments/query`
- Stream changes to matching comments as server-sent events with the listen operation
- Create a top-level comment on a document field, or a reply by setting parentCommentId
- Anchor a comment to a span of a Portable Text field with an anchor of type portable-text
- Resolve or reopen a whole thread by patching status to resolved or open
- Add or remove reactions such as :+1:, :eyes:, :heart:, or :rocket: on a comment
- Delete a comment together with all its replies in one idempotent call

## Use cases

### AI agent review assistant

An agent asked to review content can leave its notes where editors already look, as Sanity comments on the right fields. Through Jentic the agent searches for 'comment on a Sanity document', loads the create comment operation with its input schema, and posts a Portable Text message with a target documentId and path while the Sanity token is injected at call time. Comments are attributed to the token's user.

Example prompt: POST `/vX/collaboration/comments` with resourceType dataset, resourceId abcd1234.production, organizationId, and a body whose target has documentId drafts.article-1, documentType article, path body, and a Portable Text message

### Resolving feedback after edits

Once a requested change is made, the comment thread should be closed. Patching a comment's status to resolved applies to the whole thread in one mutation, and editing message records lastEditedAt, so the review history stays accurate.

Example prompt: PATCH `/vX/collaboration/comments/{id}` with resourceType dataset, resourceId abcd1234.production, organizationId, and body status resolved

### Comment digests and triage

Teams want a summary of what reviewers are asking for. A GROQ query against a resource's comments returns matching comments with their threads and status, and the listen operation streams new or changed comments as server-sent events so a digest can stay current.

Example prompt: GET `/vX/collaboration/comments/query` with resourceType dataset, resourceId abcd1234.production, organizationId, and a GROQ query selecting comments whose status is open

### Canvas document feedback

Comments also work on Canvas documents, not just dataset content. Setting resourceType to canvas and resourceId to the canvas id, against the api.sanity.io host, uses the same create, reply, reaction, and delete operations.

Example prompt: POST `/vX/collaboration/comments/{id}/reactions` with resourceType canvas, the canvas resourceId, organizationId, and shortName :+1:

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/vX/collaboration/comments/query` | Query comments with GROQ |
| GET | `/vX/collaboration/comments/listen` | Listen for comment changes |
| POST | `/vX/collaboration/comments` | Create a comment or reply |
| PATCH | `/vX/collaboration/comments/{id}` | Update a comment's message, status, or anchor |
| DELETE | `/vX/collaboration/comments/{id}` | Delete a comment and all its replies |
| POST | `/vX/collaboration/comments/{id}/reactions` | Add a reaction to a comment |

## Key resources

- **Comments** — Portable Text messages on a document or field, with threadId, status, and optional anchor
- **Threads** — A top-level comment and its replies, sharing target, status, and threadId
- **Reactions** — Per-user emoji reactions identified by shortName

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 49 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 87 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 23 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 86 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-comments-api/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Sanity Collaboration API by hand means choosing between the project host and api.sanity.io per resourceType, sending organizationId and resourceId on every comment operation, and building Portable Text message bodies. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The resource being commented on travels as the resourceId query parameter, not in the URL path, so a rule bounds which comment operations your agent may call rather than which dataset or canvas it touches. You choose the operations it may call, so deleting comments or resolving threads is not included unless you add them.
- **Credential handling:** Your Sanity token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'comment on a Sanity document' or 'resolve a Sanity comment thread', and Jentic returns the matching Collaboration operation with its required query parameters and body schema.

## Related APIs

- **Sanity HTTP API** — Query and mutate the documents comments refer to
- **Sanity Doc API** — Fetch the latest version of documents by ID
- **Liveblocks API** — Comments, threads, and real-time collaboration for your own app

## FAQ

### What authentication does the Sanity Collaboration API use?

Per its OpenAPI spec, each Sanity Collaboration API operation declares bearer authentication with your Sanity token in the Authorization header. Comments and reactions are attributed to the token's user. Through Jentic the token is stored by your own instance and attached at call time, so it stays out of the agent's context.

### How do I reply to a comment with the Sanity Collaboration API?

Create a comment with parentCommentId set to the top-level comment. The reply inherits its parent's target, status, and threadId, so do not send target or threadId with it. Replies to a reply are rejected with 400.

### Which reactions does the Sanity Collaboration API support?

The shortName enum in the spec lists :-1:, :+1:, :eyes:, :heart:, :heavy_plus_sign:, and :rocket:. Adding the same reaction again replaces it rather than adding a second one.

### Is the Sanity Collaboration API stable?

No. The spec marks vX as unstable and says it can change without notice, so pin and test any integration before relying on it.

### What are the rate limits for the Sanity Collaboration API?

The OpenAPI spec does not specify rate limits. Check the Sanity documentation at https://www.sanity.io/docs for current API limits for your plan.

### Is there a Sanity Collaboration API MCP server?

You don't need an MCP server to give your agent the Sanity Collaboration API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent loads the comment operation it needs when it needs it.

### How do I comment on a Sanity document through Jentic?

Search Jentic for 'comment on a Sanity document', load the create comment operation, and execute POST `/vX/collaboration/comments` with resourceType, resourceId, organizationId, and a body with target and message. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Sanity Collaboration API?

Yes. A rule that allows the query, listen, and create operations lets the agent read comments and post new ones and replies, while editing, resolving, and deleting stay with your editors. Every call it makes is logged.
