Codebook

A named catalogue of what the numbers a device reports mean: one entry per value, with a short name for lists and charts and an optional text wording the value as a sentence — both translatable. A schema property points here through its display spec (schema module), which may first cut the value into named fields; because an entry's text may name the other fields, each code words the rest of the value its own way — the catalogue is the case distinction.

The wording is composed at render time, in the reader's own locale. Changes are pushed as CODEBOOK_CREATE, CODEBOOK_UPDATE, CODEBOOK_ENTRIES_WRITE, CODEBOOK_ENTRY_DELETE and CODEBOOK_DELETE over the websocket.

POST	Create a codebook/api/v1/codebook
GET	List codebooks/api/v1/codebook
GET	Read one codebook/api/v1/codebook/:codebookId
PATCH	Update a codebook/api/v1/codebook/:codebookId
DELETE	Delete a codebook/api/v1/codebook/:codebookId
GET	List entries of a codebook/api/v1/codebook/:codebookId/entries
GET	Read one entry/api/v1/codebook/:codebookId/entries/:key
PUT	Write entries/api/v1/codebook/:codebookId/entries
DELETE	Delete one entry/api/v1/codebook/:codebookId/entries/:key

Create a codebook

Registers the catalogue itself — its meanings are written afterwards with PUT …/entries. codebookId is chosen by the caller and is the reference a schema holds; it cannot be changed later.

POST/api/v1/codebook

Body

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
namestring	Human-readable name of the catalogue, at most 64 characters. min length 1 · max length 64
descriptionstringoptional	What the catalogue is for; optional, at most 256 characters. max length 256
tenantIdstringoptional	Which tenant the codebook belongs to; only needed when the caller's access spans several tenants, otherwise it is inferred. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$

Response

Name	Description
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
400	A limit was reached — 64 codebooks per tenant, or 4096 entries in one codebook. message names the limit; delete what is no longer in use before writing more.	message: string
409	The tenant already has a codebook with this codebookId — write into that one with PUT …/entries, or choose another id.
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

---

List codebooks

Lists the tenant's codebooks with their metadata only. Entries never travel on a list — they are read per codebook with GET …/entries.

GET/api/v1/codebook

Response

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
namestring	Human-readable name of the catalogue, at most 64 characters. min length 1 · max length 64
descriptionstringoptional	What the catalogue is for; absent when none was written. max length 256
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource
createdAtinteger	Unix timestamp in milliseconds when this resource was created.

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 one codebook

Metadata of one codebook. The response does not grow with the catalogue — the meanings are a separate read.

GET/api/v1/codebook/fault-codes

Path Parameters

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$

Response

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
namestring	Human-readable name of the catalogue, at most 64 characters. min length 1 · max length 64
descriptionstringoptional	What the catalogue is for; absent when none was written. max length 256
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource
createdAtinteger	Unix timestamp in milliseconds when this resource was created.

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No codebook with this codebookId in the tenant, or no entry under this key. GET /codebook lists what exists.
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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

---

Update a codebook

Changes name or description; an omitted field is left alone, an explicit null clears the description. codebookId is not among them — it is the reference schemas hold.

PATCH/api/v1/codebook/fault-codes

Path Parameters

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$

Body

Name	Description
namestringoptional	New name; omitting it leaves the stored one as it is. min length 1 · max length 64
descriptionstringoptional	New description; null clears it, omitting it leaves it as it is. max length 256

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No codebook with this codebookId in the tenant, or no entry under this key. GET /codebook lists what exists.
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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 codebook

Removes the codebook together with every entry in it. Refused while any schema of the tenant still renders a field through this codebookId — drop that reference first.

DELETE/api/v1/codebook/fault-codes

Path Parameters

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No codebook with this codebookId in the tenant, or no entry under this key. GET /codebook lists what exists.
409	The delete was refused because a schema of the tenant still renders a field through this codebook. Remove or retarget that field's codebook render, then repeat the delete.	message: string
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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

---

List entries of a codebook

Every meaning in the codebook, ordered numerically by key rather than as text. Unpaged — a codebook holds at most 4096 entries.

GET/api/v1/codebook/fault-codes/entries

Path Parameters

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$

Response

Name	Description
keystring	The value this entry describes, as a decimal string, canonical: the lookup compares it verbatim, so 0001 would store and serve cleanly and then never match. Up to 20 digits, the widest unsigned 64-bit value. Pattern: ^(0|[1-9]\d{0,19})$
namestring	The label on its own — what a list, a filter or a chart shows. min length 1 · max length 96
textstringoptional	The label worded as a sentence, with {{slot}} references to the other fields of the property that selected this entry; absent means name is the whole answer. min length 1 · max length 120
i18ndictionaryoptional	Translations of name and text, keyed by locale. A reader gets the exact locale, then the bare language, then the untranslated value.
namestringoptional	Translated label. min length 1 · max length 96
textstringoptional	Translated sentence; carries its own {{slot}} references. min length 1 · max length 120
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
codebookstring	Unique Coldwave resource name (CRN) that identifies a resource
codeintegeroptional	key as a number, so a database can sort numerically — as text, 10 comes before 9. Omitted once the key grows past what a JavaScript number holds exactly. min 0 · max 9007199254740991

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No codebook with this codebookId in the tenant, or no entry under this key. GET /codebook lists what exists.
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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 one entry

One meaning, addressed by the decimal value it describes. {key} is canonical decimal — 0001 is rejected rather than read as 1.

GET/api/v1/codebook/fault-codes/entries/258

Path Parameters

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
keystring	The value this entry describes, as a decimal string, canonical: the lookup compares it verbatim, so 0001 would store and serve cleanly and then never match. Up to 20 digits, the widest unsigned 64-bit value. Pattern: ^(0|[1-9]\d{0,19})$

Response

Name	Description
keystring	The value this entry describes, as a decimal string, canonical: the lookup compares it verbatim, so 0001 would store and serve cleanly and then never match. Up to 20 digits, the widest unsigned 64-bit value. Pattern: ^(0|[1-9]\d{0,19})$
namestring	The label on its own — what a list, a filter or a chart shows. min length 1 · max length 96
textstringoptional	The label worded as a sentence, with {{slot}} references to the other fields of the property that selected this entry; absent means name is the whole answer. min length 1 · max length 120
i18ndictionaryoptional	Translations of name and text, keyed by locale. A reader gets the exact locale, then the bare language, then the untranslated value.
namestringoptional	Translated label. min length 1 · max length 96
textstringoptional	Translated sentence; carries its own {{slot}} references. min length 1 · max length 120
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
codebookstring	Unique Coldwave resource name (CRN) that identifies a resource
codeintegeroptional	key as a number, so a database can sort numerically — as text, 10 comes before 9. Omitted once the key grows past what a JavaScript number holds exactly. min 0 · max 9007199254740991

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No codebook with this codebookId in the tenant, or no entry under this key. GET /codebook lists what exists.
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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 entries

Upserts by key — an entry named here replaces the stored one wholesale, one not named is left alone, so this PUT never empties a catalogue. At most 500 entries per call and 4096 per codebook; removing a meaning is an explicit DELETE.

PUT/api/v1/codebook/fault-codes/entries

Path Parameters

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$

Body

Name	Description
entriesarray	The entries to write — 1 to 500 per call, and unique by key within one body.
keystring	The value this entry describes, as a decimal string, canonical: the lookup compares it verbatim, so 0001 would store and serve cleanly and then never match. Up to 20 digits, the widest unsigned 64-bit value. Pattern: ^(0|[1-9]\d{0,19})$
namestring	The label on its own, 1 to 96 characters — what a list, a filter or a chart shows. min length 1 · max length 96
textstringoptional	The label worded as a sentence; every {{…}} must be a field slot, or the write is rejected. Absent means name is the whole answer. min length 1 · max length 120
i18ndictionaryoptional	Translations of name and text, keyed by locale such as de-DE; at most 16 locales.
namestringoptional	Translated label. min length 1 · max length 96
textstringoptional	Translated sentence; carries its own {{slot}} references. min length 1 · max length 120

Response

Name	Description
writteninteger	How many entries the request carried — what was sent, not what actually changed. min 0

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No codebook with this codebookId in the tenant, or no entry under this key. GET /codebook lists what exists.
400	A limit was reached — 64 codebooks per tenant, or 4096 entries in one codebook. message names the limit; delete what is no longer in use before writing more.	message: string
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

---

Delete one entry

Removes one meaning from the codebook. A value that no longer has an entry still renders — as its bare number.

DELETE/api/v1/codebook/fault-codes/entries/258

Path Parameters

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
keystring	The value this entry describes, as a decimal string, canonical: the lookup compares it verbatim, so 0001 would store and serve cleanly and then never match. Up to 20 digits, the widest unsigned 64-bit value. Pattern: ^(0|[1-9]\d{0,19})$

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No codebook with this codebookId in the tenant, or no entry under this key. GET /codebook lists what exists.
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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
CODEBOOK_CREATE	A codebook was registered — metadata only, still without any entries.
CODEBOOK_DELETE	A codebook was removed together with all of its entries.
CODEBOOK_ENTRIES_WRITE	Meanings were written as one batch — an import of several hundred is a single event, not several hundred.
CODEBOOK_ENTRY_DELETE	A single meaning was removed from a codebook.
CODEBOOK_UPDATE	The name or description of a codebook was changed; carries the merged document.

Codebook created

A codebook was registered — metadata only, still without any entries.

EVENTCODEBOOK_CREATE

Payload

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
namestring	Human-readable name of the catalogue, at most 64 characters. min length 1 · max length 64
descriptionstringoptional	What the catalogue is for; absent when none was written. max length 256
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource
createdAtinteger	Unix timestamp in milliseconds when this resource was created.

Codebook deleted

A codebook was removed together with all of its entries.

EVENTCODEBOOK_DELETE

Payload

Name	Description

Entries written

Meanings were written as one batch — an import of several hundred is a single event, not several hundred.

EVENTCODEBOOK_ENTRIES_WRITE

Payload

Name	Description
entriesarray	The entries the write carries — a batch of codebook meanings, or a user's key/value map.
keystring	The value this entry describes, as a decimal string, canonical: the lookup compares it verbatim, so 0001 would store and serve cleanly and then never match. Up to 20 digits, the widest unsigned 64-bit value. Pattern: ^(0|[1-9]\d{0,19})$
namestring	The label on its own — what a list, a filter or a chart shows. Up to 96 characters, because these are written alongside the firmware rather than filed by hand. min length 1 · max length 96
textstringoptional	The label worded as a sentence, with {{slot}} references to the other fields of the property that selected this entry. Absent means name is the whole answer. min length 1 · max length 120
i18ndictionaryoptional	Translations of this entry, keyed by locale, at most 16 of them. Rendering takes the exact locale, then the bare language, then the entry's own wording, so a partial translation is fine.
namestringoptional	Translated name; falls back to the entry's own when this locale does not carry it. min length 1 · max length 96
textstringoptional	Translated text; falls back to the entry's own when this locale does not carry it. min length 1 · max length 120
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
codebookstring	Unique Coldwave resource name (CRN) that identifies a resource
codeintegeroptional	key as a number, written only so an editor can sort in the database — sorted as text, 10 comes before 9. Omitted above 2^53, where a JavaScript number stops being exact. min 0 · max 9007199254740991

Entry deleted

A single meaning was removed from a codebook.

EVENTCODEBOOK_ENTRY_DELETE

Payload

Name	Description

Codebook updated

The name or description of a codebook was changed; carries the merged document.

EVENTCODEBOOK_UPDATE

Payload

Name	Description
codebookIdstring	Slug naming the codebook, chosen by the caller rather than generated: a schema references a catalogue by it, so deleting and re-importing has to land on the same name. Lowercase letters, digits and -, 2 to 63 characters. Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
namestring	Human-readable name of the catalogue, at most 64 characters. min length 1 · max length 64
descriptionstringoptional	What the catalogue is for; absent when none was written. max length 256
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource
createdAtinteger	Unix timestamp in milliseconds when this resource was created.