Caching

Last updated Jun 14, 2026

Matter returns ETags on resource GET endpoints where caching is cheap and safe. Use conditional requests to avoid re-fetching and re-serializing unchanged resources.

ETag on retrieve

GET /v1/entities/ent_Nq3KcAbc HTTP/1.1

HTTP/1.1 200 OK
ETag: W/"sha256:9f86d08..."
Cache-Control: private, max-age=10
Content-Type: application/json

On a subsequent request, send If-None-Match with the ETag:

GET /v1/entities/ent_Nq3KcAbc HTTP/1.1
If-None-Match: W/"sha256:9f86d08..."

HTTP/1.1 304 Not Modified

You still spend a round trip, but the body is empty — useful for polling loops where the resource is usually unchanged (e.g., watching an entity in registered state until it hits active).

Cache-Control values

Don't cache errors

RFC 7807 problem responses carry Cache-Control: no-store. Errors are never cached because retrying may produce a different result.

Best practices

• Use conditional requests for polling loops — cheaper than re-fetching bodies.
• Never cache across keys or tokens. Each consumer has its own view.
• Never cache POST responses.
• Don't cache list responses. They're paginated and their membership changes.

Implementation example

async function pollUntilActive(entityId) {
  let etag = null;
  while (true) {
    const headers = { Authorization: `Bearer ${KEY}`, "Matter-Version": "2026-05-01" };
    if (etag) headers["If-None-Match"] = etag;
    const res = await fetch(`https://api.mattermode.com/v1/entities/${entityId}`, { headers });
    if (res.status === 304) {
      await sleep(2000);
      continue;
    }
    etag = res.headers.get("ETag");
    const entity = await res.json();
    if (entity.status === "active") return entity;
    await sleep(2000);
  }
}

For long polling, prefer webhooks or the SSE stream — conditional-GET polling works but is not the fastest path to "operational" state.