Userdata

One document per account: the resource is derived from the authenticated account, so the ordinary routes reach only the caller's own. It holds a flat map of keys to base64 strings — layouts, preferences, per-account client state — that no route reads into. A value has to fit into one request body, and no route splits or reassembles one, so larger state is spread over several keys by the client.

Tenant-wide storage of the same kind is data, which keeps structured JSON instead. Every write is published as USERDATA_SET or USERDATA_DELETE over the websocket; the Application Developer Guide names both as places application state can live.

POST	Write one entry/api/v1/userdata/:key
POST	Write one entry via body/api/v1/userdata
GET	Read all entries/api/v1/userdata
GET	Compare cache and database/api/v1/userdata/debug/all
DELETE	Delete all entries/api/v1/userdata
GET	Read one entry/api/v1/userdata/:key
DELETE	Delete one entry/api/v1/userdata/:key

Write one entry

Merges one entry into the caller's own document — other keys stay, an existing key is overwritten. Keys admit no digits; values have to be base64.

POST/api/v1/userdata/dashboard.layout

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 Pattern: ^[a-zA-Z._\\-]+$

Body

Name	Description
valuestring	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64. Pattern: ^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$

Errors

Status	Description	Body
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

---

Write one entry via body

The same write with key in the body instead of the path; the entry is merged into the caller's document either way.

POST/api/v1/userdata

Body

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 Pattern: ^[a-zA-Z._\\-]+$
valuestring	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64. Pattern: ^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$

Errors

Status	Description	Body
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

---

Read all entries

Every entry of the caller's own document, keys mapped to their base64 values. With nothing stored the answer is an empty object, never a 404.

GET/api/v1/userdata

Response

Name	Description

Errors

Status	Description	Body
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

---

Compare cache and database

Diagnostic listing of every stored document of every tenant, with the cache copy and the database copy side by side and deliberately not reconciled. Requires read on crn#*; a tenant-wide administrator does not qualify.

GET/api/v1/userdata/debug/all

Response

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
rehydratedboolean	Whether this tenant's userdata has been rehydrated yet. It tells a copy that is merely not loaded apart from one that is genuinely absent.
databaseobjectoptional	The database store — on the health route its connection state, in the userdata diagnostic the persisted copy or null. It sits beside the cached copy rather than being reconciled with it: a document present in only one store is the failure worth finding.
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
userstring	Unique Coldwave resource name (CRN) that identifies a resource
entriesdictionary	The stored key/value pairs as the database holds them; values are base64.
createdAtinteger	Unix timestamp in milliseconds when this resource was created.
cacheobjectoptional	The cache store — on the health route its connection state, in the userdata diagnostic the copy the cache holds, or null when it holds none.
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
userstring	Unique Coldwave resource name (CRN) that identifies a resource
entriesdictionary	The stored key/value pairs as the database holds them; values are base64.
createdAtinteger	Unix timestamp in milliseconds when this resource was created.

Errors

Status	Description	Body
403	You do not have permission to perform this action
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 all entries

Removes the caller's whole document in one call, and succeeds when there was nothing to remove.

DELETE/api/v1/userdata

Errors

Status	Description	Body
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 one entry

The value stored under one key, byte for byte as it was written. A missing key is a 404 here, while the full listing answers with an empty object.

GET/api/v1/userdata/dashboard.layout

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 Pattern: ^[a-zA-Z._\\-]+$

Response

Name	Description
valuestring	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64. Pattern: ^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$

Errors

Status	Description	Body
404	No entry under this key in the caller's document. Only the single-key read reports this — the full listing answers with an empty object, and both delete routes succeed either way.
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 one entry

Removes one key and leaves the rest of the document standing. A key that was never there is not an error, and the change is reported as USERDATA_SET — USERDATA_DELETE belongs to the whole-document delete.

DELETE/api/v1/userdata/dashboard.layout

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 Pattern: ^[a-zA-Z._\\-]+$

Errors

Status	Description	Body
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
USERDATA_DELETE	A user's document was deleted as a whole; removing a single key reports as USERDATA_SET instead.
USERDATA_SET	A user's stored key/value document was written. The payload is the whole document after the change, whether a key was added, overwritten or removed.

Userdata cleared

A user's document was deleted as a whole; removing a single key reports as USERDATA_SET instead.

EVENTUSERDATA_DELETE

Payload

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
userstring	Unique Coldwave resource name (CRN) that identifies a resource
entriesdictionary	The entries the write carries — a batch of codebook meanings, or a user's key/value map.
createdAtinteger	Unix timestamp in milliseconds when this resource was created.

Userdata written

A user's stored key/value document was written. The payload is the whole document after the change, whether a key was added, overwritten or removed.

EVENTUSERDATA_SET

Payload

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
userstring	Unique Coldwave resource name (CRN) that identifies a resource
entriesdictionary	The entries the write carries — a batch of codebook meanings, or a user's key/value map.
createdAtinteger	Unix timestamp in milliseconds when this resource was created.