Collection Endpoint vs Static Payload: Which Should You Use?

Use a collection endpoint when you need a history of many records. Use a static payload when you need one current JSON document, such as device settings, feature flags, or the latest control state.

Question	Collection	Static payload
What does it model?	Many typed records	One JSON document
Best for	Sensor history, events, submissions	Current settings, state, flags
Does it preserve history?	Yes, one record per event	No, updates replace the document
Can a dashboard read it?	Yes, collection widgets show current values	Yes, widgets can bind to nested keys

Choose a collection for history

A collection is the natural model for readings, events, inventories, answers, or anything where each occurrence matters. A Weather Station might create one record every five minutes:

{"temperature":22.5,"humidity":54.2}Code language: JSON / JSON with Comments (json)

The API validates each record against the schema and returns a UUID and timestamps. Later, you can filter, aggregate, paginate, or export the history.

Choose static payload for current state

A static endpoint is a single document. It suits configuration a device polls or a dashboard controls:

{
  "camera": {"thresholds": {"confidence": 0.65}},
  "enabled": true
}Code language: JSON / JSON with Comments (json)

When you update the confidence value, the current document changes. There is no automatic record of every previous value, so create a collection as well if audit history matters.

Dashboard implications

• Collection widgets display values from the latest record; they do not edit collection history.
• Static payload widgets can bind to a nested key such as camera.thresholds.confidence and write a new current value.
• Use a static endpoint for remote configuration and a collection for telemetry.
• Do not overload one endpoint with two meanings just to avoid creating a second resource.

A simple decision flow

1. Will you need to compare values over time? Choose a collection.
2. Is there only one current document? Choose static payload.
3. Does a device need both telemetry and settings? Create one endpoint of each type.
4. Will a dashboard user change the value? Bind a static key to an interactive widget.

Next step

Once the data model is chosen, build a control panel in Build Your First Meow Meow Scratch Dashboard, or learn the endpoint vocabulary in What Is an API Endpoint?.