Product Record reference #

Product Records follow the model and field definitions in the Product Instance's published application version. Use the generated instance contract for paths and request schemas.

Reading requires records:read, model:<key>:read, or *. Writing requires records:write, model:<key>:write, or *. The model must also permit the requested customer action.

Read records #

List and detail responses use the standard record envelope described in the Product Application API overview. Detail reads return active records; archived records are excluded.

data_by_key is the convenient application-facing representation. data is keyed by field stable ID. Use only fields in the generated contract rather than depending on undeclared stable IDs. The fields array describes visible fields, including their key, stable ID, label, field type, writable and required flags, and published relationship metadata.

Create records #

Send values using published field keys. A create succeeds only when the model allows creation and the payload satisfies required fields, field validation, write policy, and relationship integrity. The response is the created record with record_version set to 1.

Unknown fields and non-writable fields are validation errors. Computed, stream-derived, system-ID, internal-only, and immutable fields follow the published access policy rather than accepting arbitrary client values.

Update records #

Updates merge the supplied writable fields into the record. Include the current record_version when concurrent writers could update the same record. On success, the API increments record_version.

If the supplied version is stale, the API returns 409 and the current version:

json

{
  "detail": "Conflict",
  "record_version": 7
}

Read the latest record, reconcile the caller's intended change, and retry with a new idempotency key. Do not overwrite a conflict without applying the business system's authority rules.

Preserve relationship integrity #

A record reference must point to a record in the same Product Instance. When the field declares a target model, the target must belong to that model. Archived targets are rejected unless the published relationship policy explicitly allows them.

Native customer, site, device, user, and Device Class binding references are checked against the Product Instance's tenant and published bindings. Invalid cross-tenant references are reported as invalid rather than revealing whether the target exists elsewhere.

Handle secret fields #

Secret fields are write-only. Dataplicity hashes their values at rest and never returns plaintext or the stored hash. A set value is presented as:

json

{ "set": true }

An unset value is null. On update, sending null, an empty value, or the {"set": true} marker leaves an existing secret unchanged. Send a new plaintext value only when setting or rotating the secret.

Archive records #

Deleting a Product Record archives it; it does not remove the row. Archiving is available only when the published model permits customer deletion.

The default relationship policy is restrictive. A record cannot be archived while another active record in the same instance refers to it. Remove or replace those references first. Archived records disappear from normal list, query, and detail reads; permitted queries can opt into them with include_archived.

Use idempotency keys #

Send Idempotency-Key for create, update, and archive requests. Repeating the same mutation with the same API client and key returns the original status and body. Reusing the key with a different method, target, or body returns 409.

An idempotency key protects the cloud-side record mutation. If that mutation starts another workflow, verify its eventual business or device outcome separately.