HTTP API Reference

Comments API reference

Create, update and delete comments and reactions through the Collaboration HTTP API.

Create, update and delete comments and their reactions in the organization store that owns a resource. Reads are the query and listen endpoints, which the gateway serves from the organization store, not this service. vX is unstable and can change without notice.

Base API server URL

Dataset comments (resourceType=dataset).

https://{projectId}.api.sanity.io

Variables

  • projectIdstringdefault: "your-project-id"

    Project that owns the dataset.

Canvas comments (resourceType=canvas).

https://api.sanity.io

Endpoints

Query comments

get/vX/collaboration/comments/query

Runs a GROQ query against the comments of a resource. The gateway serves it from the organization store, not this service, and it behaves like the standard query endpoint.

Query parameters

  • querystringrequired

    GROQ query over the resource’s comments. Pass each query parameter as its own $name=<JSON value>, for example $documentId="article-1".

  • organizationIdstringrequired

    Organization that owns the resource and its comment store.

  • resourceTypestringrequired

    Kind of resource the comment belongs to: dataset for a document in a project dataset, canvas for a Canvas document.

  • resourceIdstringrequired

    Id of the resource: projectId.dataset for dataset, the canvas id for canvas. Must not contain :.

Responses

200

The query result.

  • resultrequired

    Whatever the query returns.

Query comments with a request body

post/vX/collaboration/comments/query

Runs a GROQ query against the comments of a resource. The gateway serves it from the organization store, not this service, and it behaves like the standard query endpoint. Use it when the query and parameters don't fit in a URL.

Query parameters

  • organizationIdstringrequired

    Organization that owns the resource and its comment store.

  • resourceTypestringrequired

    Kind of resource the comment belongs to: dataset for a document in a project dataset, canvas for a Canvas document.

  • resourceIdstringrequired

    Id of the resource: projectId.dataset for dataset, the canvas id for canvas. Must not contain :.

Request body application/json

  • querystringrequired

    GROQ query over the resource’s comments.

  • paramsobject

    Query parameters by name, without the $. For example {"documentId": "article-1"}.

Responses

200

The query result.

  • resultrequired

    Whatever the query returns.

Listen for comment changes

get/vX/collaboration/comments/listen

Streams changes to the comments a GROQ query matches, as server-sent events. The gateway serves it from the organization store, not this service, and it behaves like the standard listen endpoint, including its options such as includeResult and visibility.

Query parameters

  • querystringrequired

    GROQ query over the resource’s comments. Pass each query parameter as its own $name=<JSON value>, for example $documentId="article-1".

  • organizationIdstringrequired

    Organization that owns the resource and its comment store.

  • resourceTypestringrequired

    Kind of resource the comment belongs to: dataset for a document in a project dataset, canvas for a Canvas document.

  • resourceIdstringrequired

    Id of the resource: projectId.dataset for dataset, the canvas id for canvas. Must not contain :.

Responses

200

An event stream of welcome, mutation and other listen events.

  • string

Create a comment

post/vX/collaboration/comments

Creates a top-level comment on target, or a reply when parentCommentId is set. A reply inherits its parent’s target, status and threadId, so don’t send target or threadId with it. Replies to a reply are rejected with 400. Top-level comments start as open.

Query parameters

  • resourceTypestringrequired

    Kind of resource the comment belongs to: dataset for a document in a project dataset, canvas for a Canvas document.

  • resourceIdstringrequired

    Id of the resource: projectId.dataset for dataset, the canvas id for canvas. Must not contain :.

  • organizationIdstringrequired

    Organization that owns the resource and its comment store.

  • transactionIdstring

    Transaction id for the store mutation. Set it to recognize your own write when it comes back through a listener.

  • clientVersionstring

    Version of the calling @sanity/client, for telemetry.

Request body application/json

  • _idstring

    _id for the comment. Server-generated if omitted.

  • targetobject

    What the comment targets. Required when parentCommentId is not set.

    Show child attributes
    • documentIdstringrequired

      Id of the document the comment is on, for example drafts.article-1, without the resource prefix. Must not contain :.

    • documentTypestringrequired

      _type of that document.

    • documentRevisionIdstring

      Revision of the document the comment was written against.

    • pathstring

      Field the comment is on, for example body. Required with anchor. Omit it for a document-level comment.

    • anchor

      Where in path the comment is anchored.

      Show child attributes
      • typestringrequired
      • startobjectrequired
        Show child attributes
      • endobjectrequired
        Show child attributes
      • fieldValuearray

        Portable Text covering the anchor (at least from start to end _key). When set, resolves the selection without fetching the source document. The full field also works.

        Show child attributes
        items
    • rangedeprecated

      Deprecated, use anchor.

      Show child attributes
      • startobjectrequired
        Show child attributes
      • endobjectrequired
        Show child attributes
    • fieldValuearraydeprecated

      Deprecated, use anchor.fieldValue.

      Show child attributes
      items
  • parentCommentIdstring

    When set, creates a reply to this comment.

  • threadIdstring

    threadId for a top-level comment. Server-generated if omitted. Not allowed on replies — replies inherit the parent's threadId.

  • messagearrayrequired

    Comment body as Portable Text.

    Show child attributes
    items
  • contextobject

    Free-form metadata stored as-is on the comment.

Responses

200

The mutation result: transactionId and one results entry per document changed (a thread change includes every reply).

Delete a comment and all its replies

delete/vX/collaboration/comments/{id}

Deletes the comment and its replies in one mutation. Idempotent: deleting a comment that doesn’t exist returns 200 with empty results, not 404.

Path parameters

  • idstringrequired

    _id of the comment.

Query parameters

  • resourceTypestringrequired

    Kind of resource the comment belongs to: dataset for a document in a project dataset, canvas for a Canvas document.

  • resourceIdstringrequired

    Id of the resource: projectId.dataset for dataset, the canvas id for canvas. Must not contain :.

  • organizationIdstringrequired

    Organization that owns the resource and its comment store.

  • transactionIdstring

    Transaction id for the store mutation. Set it to recognize your own write when it comes back through a listener.

  • clientVersionstring

    Version of the calling @sanity/client, for telemetry.

Responses

200

The mutation result: transactionId and one results entry per document changed (a thread change includes every reply).

Update a comment

patch/vX/collaboration/comments/{id}

Changes the message, status or anchor. status and anchor apply to the whole thread: the comment and all its replies change in one mutation. Editing message sets lastEditedAt. Only top-level comments that target a field can be anchored.

Path parameters

  • idstringrequired

    _id of the comment.

Query parameters

  • resourceTypestringrequired

    Kind of resource the comment belongs to: dataset for a document in a project dataset, canvas for a Canvas document.

  • resourceIdstringrequired

    Id of the resource: projectId.dataset for dataset, the canvas id for canvas. Must not contain :.

  • organizationIdstringrequired

    Organization that owns the resource and its comment store.

  • transactionIdstring

    Transaction id for the store mutation. Set it to recognize your own write when it comes back through a listener.

  • clientVersionstring

    Version of the calling @sanity/client, for telemetry.

Request body application/json

  • messagearray

    New comment body as Portable Text. Sets lastEditedAt.

    Show child attributes
    items
  • statusstring

    open or resolved. Applies to the whole thread.

  • anchor

    Where in path the comment is anchored, as on create. null removes the anchor, leaving a field-level comment.

    Show child attributes
    • typestringrequired
    • startobjectrequired
      Show child attributes
    • endobjectrequired
      Show child attributes
    • fieldValuearray

      Portable Text covering the anchor (at least from start to end _key). When set, resolves the selection without fetching the source document. The full field also works.

      Show child attributes
      items
  • rangedeprecated

    Deprecated, use anchor.

    Show child attributes
    • startobjectrequired
      Show child attributes
    • endobjectrequired
      Show child attributes
  • fieldValuearraydeprecated

    Deprecated, use anchor.fieldValue.

    Show child attributes
    items

Responses

200

The mutation result: transactionId and one results entry per document changed (a thread change includes every reply).

Add a reaction to a comment

post/vX/collaboration/comments/{id}/reactions

Adds the token user’s reaction. Idempotent per user and reaction: adding the same reaction again replaces it rather than adding a second one.

Path parameters

  • idstringrequired

    _id of the comment.

Query parameters

  • resourceTypestringrequired

    Kind of resource the comment belongs to: dataset for a document in a project dataset, canvas for a Canvas document.

  • resourceIdstringrequired

    Id of the resource: projectId.dataset for dataset, the canvas id for canvas. Must not contain :.

  • organizationIdstringrequired

    Organization that owns the resource and its comment store.

  • transactionIdstring

    Transaction id for the store mutation. Set it to recognize your own write when it comes back through a listener.

  • clientVersionstring

    Version of the calling @sanity/client, for telemetry.

Request body application/json

Responses

200

The mutation result: transactionId and one results entry per document changed (a thread change includes every reply).

Remove a reaction from a comment

delete/vX/collaboration/comments/{id}/reactions/{shortName}

Removes the token user’s reaction.

Path parameters

  • idstringrequired

    _id of the comment.

  • shortNamestringrequired

    Reaction to remove.

Query parameters

  • resourceTypestringrequired

    Kind of resource the comment belongs to: dataset for a document in a project dataset, canvas for a Canvas document.

  • resourceIdstringrequired

    Id of the resource: projectId.dataset for dataset, the canvas id for canvas. Must not contain :.

  • organizationIdstringrequired

    Organization that owns the resource and its comment store.

  • transactionIdstring

    Transaction id for the store mutation. Set it to recognize your own write when it comes back through a listener.

  • clientVersionstring

    Version of the calling @sanity/client, for telemetry.

Responses

200

The mutation result: transactionId and one results entry per document changed (a thread change includes every reply).

Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change site theme