HTTP API Reference

Listen API reference

Reference documentation for the Listen HTTP endpoint.

The listen endpoint can be used to receive events whenever documents are modified. This endpoint follows the server-sent events protocol using the mime-type text/event-stream. The backend will hold the connection open and stream events as they occur for any documents matching the GROQ query.

In most cases, you should use the Live Content API instead for new projects.

Authentication

Base API server URL

Sanity API base URL

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

Variables

  • projectIdstringdefault: "projectId"

    Project ID

  • apiVersionstringdefault: "v2025-02-19"

    API version

Endpoints

Stream document mutation events

get/data/listen/{dataset}

Streams events whenever documents matching the GROQ query are modified. This is a live API adhering to the Server Sent Events standard.

Path parameters

  • datasetstringrequired

    The dataset to stream events from

Query parameters

  • querystringrequired

    The GROQ-query used to filter the events. Only the top-level filter portion of the query will be used, anything else including projection, subqueries, slicing or aggregation will be ignored.

  • $-paramsstring
  • includeResultbooleandefault: false

    Include the resulting document in addition to the changes.

  • includePreviousRevisionbooleandefault: false

    Include the document as it looked before the change.

  • includeMutationsbooleandefault: true

    Include the mutations applied as part of the transaction.

  • visibilitystringdefault: "transaction"

    Specifies whether events should be sent as soon as a transaction has been committed (transaction, default), or only after they are available for queries (query). Note that this is best-effort, and listeners with query may in certain cases (notably with deferred transactions) receive events that are not yet visible to queries. The visibility event field will indicate the actual visibility.

  • evs_preamblebooleandefault: false

    Send a prolog of 2056 no-op characters for compatibility with older browsers.

  • effectFormatstring

    If set to the only allowed value mendoza, an additional field effects is included in the returned payload with mutation effects in the Mendoza specification.

  • includeAllVersionsbooleandefault: false

    Set to true to receive draft and version documents. Requires API version 2025-02-19.

Responses

200

Successfully started streaming operation

  • idstring

    A unique id for this event, comprised of the transaction id and the document id

  • eventstring

    The type of SSE message

  • dataobject

    The message payload

Examplestext/event-stream
welcome
{
  "event": "welcome",
  "data": {
    "listenerName": "Ua6BR3GwQ14cnZXrgwCdsF"
  }
}