Real-Time Media ConductorLearn · Shared context
Artifacts
Store identified results that clients can read, update, and follow across reconnects.
An artifact is an identified, versioned result stored in a room. Examples include reports, plans, and generated documents: consumers care about its current contents and can refer to it by ID.
Give a result a stable identity
// room has artifact:write on report. This example creates a new artifact.
const report = await room.putArtifact({
id: "shipment-summary",
type: "report",
content: {title: "Shipment summary", text: "The package is in transit."},
expectedVersion: 0,
});
console.log(report.id, report.version, report.status);
The ID lets clients refer to the same result as its contents change. The type classifies it, such as report, and determines which artifact grants apply.
Choose the right representation
| Product need | Representation |
|---|---|
| Record that a report was requested | An event or delegation request |
| Store the current report itself | An artifact with a stable ID |
| Keep a small shared preference or context value | A state document addressed by key |
| Show a live progress meter | Local UI or provider state, unless a durable milestone matters |
A delegation result does not automatically become the application artifact you designed. Your integration chooses when and how to persist an accepted result through the artifact API.
Update without overwriting unseen work
Write the same artifact ID with its last observed expectedVersion to update it. A version conflict means the stored result changed since your read; fetch current context and reconcile. Passing zero expects the artifact not to exist. Omitting the expected version gives up this check.
As with state writes, the SDK generates a new event ID for each putArtifact() call. It does not expose a reusable publication key in this helper. Account for an uncertain HTTP result before retrying a versioned mutation.
Read current results and changes
Snapshots include artifacts allowed by artifact:read on their type and their visibility. Following the corresponding artifact.upserted events requires separate event-subscription authority. Apply versions monotonically when combining snapshot hydration and replay.
See the artifact write path, SQLite artifact storage, and the SDK helper. Continue with authorization for projection and event grants.