Data

Tenant-wide JSON documents, one per key: application data that belongs to the organisation rather than to a single device. The key is part of the document's CRN (crn#tenant:….data:<key>), so an access rule can name one document instead of the whole store. A value is a JSON object of up to 4 MiB, assembled from RFC 7396 merge patches when it outgrows one request body.

The per-account counterpart is userdata, which stores opaque base64 rather than readable JSON. Writes are published as DATA_SET and DATA_DELETE over the websocket; the surrounding data model is covered by the Application Developer Guide.

GET	List data keys/api/v1/data
GET	Read a document/api/v1/data/:key
PUT	Replace a document/api/v1/data/:key
PATCH	Merge into a document/api/v1/data/:key
DELETE	Delete a document/api/v1/data/:key

List data keys

Lists the tenant's keys with their CRNs, and no values at all: a document is read only by a caller that names its key. Keys the caller has no read on are left out silently.

GET/api/v1/data

Response

Name	Description
keystring	Key one value is stored under. The accepted characters are narrower than a free string — see pattern — because the key is part of how the value is addressed. min length 1 · max length 128 Pattern: ^[A-Za-z0-9_-]+$
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Read a document

Returns the stored document in full — value plus who created it and when it last changed. There is no paging, so a value assembled from many PATCH calls arrives in a single response, up to 4 MiB of it.

GET/api/v1/data/fault-codes

Path Parameters

Name	Description
keystring	Key one value is stored under. The accepted characters are narrower than a free string — see pattern — because the key is part of how the value is addressed. min length 1 · max length 128 Pattern: ^[A-Za-z0-9_-]+$

Response

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
keystring	Key one value is stored under. The accepted characters are narrower than a free string — see pattern — because the key is part of how the value is addressed. min length 1 · max length 128 Pattern: ^[A-Za-z0-9_-]+$
valuedictionary	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.
createdBystring	Resource identifier of the entity that created this resource
createdAtinteger	Unix timestamp in milliseconds when this resource was created.
updatedAtinteger	Unix timestamp in milliseconds when this resource was last modified.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
404	No document is stored under this key in the tenant — it was never written, or it has been deleted. GET /data lists the keys the caller can see; only PUT creates one.
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Replace a document

Writes value over whatever the key held, creating the document when the key is free — which needs create access rather than update. Deliberately unlocked: of two concurrent replacements the later one wins, so a document larger than one request body is assembled with PATCH instead.

PUT/api/v1/data/fault-codes

Path Parameters

Name	Description
keystring	Key one value is stored under. The accepted characters are narrower than a free string — see pattern — because the key is part of how the value is addressed. min length 1 · max length 128 Pattern: ^[A-Za-z0-9_-]+$

Body

Name	Description
valuedictionary	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
413	The value — for a PATCH, the result of the merge — exceeds the 4 MiB a stored document may occupy. Drop entries by patching them to null, or spread the content over several keys; splitting the same content into more patches does not help.
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Merge into a document

Applies value as an RFC 7396 merge patch: a null removes the key it sits on, arrays are replaced whole. Never creates — an unknown key answers 404 — and merges under a short lock, so a 409 means the same patch has to be sent again, not that the write failed.

PATCH/api/v1/data/fault-codes

Path Parameters

Name	Description
keystring	Key one value is stored under. The accepted characters are narrower than a free string — see pattern — because the key is part of how the value is addressed. min length 1 · max length 128 Pattern: ^[A-Za-z0-9_-]+$

Body

Name	Description
valuedictionary	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
404	No document is stored under this key in the tenant — it was never written, or it has been deleted. GET /data lists the keys the caller can see; only PUT creates one.
409	Another merge into this key holds the lock, which expires within seconds. This is contention, not failure: back off briefly and re-send the same patch — re-applying it leaves the value unchanged, but still refreshes updatedAt and emits another DATA_SET.
413	The value — for a PATCH, the result of the merge — exceeds the 4 MiB a stored document may occupy. Drop entries by patching them to null, or spread the content over several keys; splitting the same content into more patches does not help.
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Delete a document

The answer is not idempotent — a repeated call gets 404. Whole documents only: a single key inside value is removed by a PATCH that sets it to null.

DELETE/api/v1/data/fault-codes

Path Parameters

Name	Description
keystring	Key one value is stored under. The accepted characters are narrower than a free string — see pattern — because the key is part of how the value is addressed. min length 1 · max length 128 Pattern: ^[A-Za-z0-9_-]+$

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
404	No document is stored under this key in the tenant — it was never written, or it has been deleted. GET /data lists the keys the caller can see; only PUT creates one.
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Events

Published on the tenant's event stream and delivered over the websocket to every subscriber holding read on the resource the message names. resourceIdentifier is the resource the action changed; the payload is the shape below.

Event	Description
DATA_DELETE	A document was removed; the payload is empty, so the key it held is read from the CRN.
DATA_SET	A document was replaced or merged; the payload is the whole stored entry after the write, not the patch that caused it.

Document deleted

A document was removed; the payload is empty, so the key it held is read from the CRN.

EVENTDATA_DELETE

Payload

Name	Description

Document written

A document was replaced or merged; the payload is the whole stored entry after the write, not the patch that caused it.

EVENTDATA_SET

Payload

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
keystring	Key one value is stored under. The accepted characters are narrower than a free string — see pattern — because the key is part of how the value is addressed. min length 1 · max length 128 Pattern: ^[A-Za-z0-9_-]+$
valuedictionary	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.
createdBystring	Resource identifier of the entity that created this resource
createdAtinteger	Unix timestamp in milliseconds when this resource was created.
updatedAtinteger	Unix timestamp in milliseconds when this resource was last modified.