Download OpenAPI specification:
Document-centric transmission cache — REST API reference.
TamaDB is a document-centric transmission cache for smart-endpoints / dumb-pipes architectures: a JSON document-oriented cache engine that validates, versions, and delivers producer data to consumers. This is the complete REST API reference for Increment 1.
This document is the single source of truth for the TamaDB HTTP surface.
It is linted in CI (redocly lint) and rendered to the published API
Reference by Redoc, so the docs cannot silently drift from the contract.
application/json, except the ingestion
endpoints, whose request body is the bare JSON document (see
Ingestion)./api/v1 prefix except GET /health.{paramName}.TamaDB documents are upserted — there is no separate create vs update.
The first ingest of a given identity creates the document (HTTP 201); a
subsequent ingest of the same identity merges into it (HTTP 200),
preserving absent leaves and incrementing the version number.
A document's identity (D-Id) is derived from one or more payload fields
annotated with the identityKind keyword in the schema. Identity is scoped
to (Document_Type, D-Id).
identityKind is a custom (vendor) JSON Schema keyword that TamaDB reads
from registered schemas to extract the D-Id. It is attached to scalar
leaf properties and takes one of two values:
primary-key — a field that contributes to the document's own identity.parent-key — a field that contributes a parent/ancestor identity segment.It may be annotated at any object-nesting depth (universal nested-path
identity, since 0.2.0); the field is addressed by its root-to-leaf
Identity_Path. Arrays are never traversed (atomic in Increment 1) and the
annotated value must be a scalar. The keyword is ignored by schema
validation (Ajv runs with strict: false) and consumed only by the D-Id
Extractor. It is therefore a property of the posted schema, not a
request/response field. See the Schemas tag for how to register a schema
carrying identityKind.
A composed (multi-field) D-Id is expressed in a URL by joining its parts
with the : delimiter. Each part is percent-encoded (via
encodeURIComponent, and : is additionally encoded as %3A) so that a
part value may itself contain the delimiter, /, or other reserved
characters without corrupting the part boundaries. In response bodies, a
single-key dId is a string and a composed dId is an array of strings.
A cached document's TTL is a sliding window anchored to its last update
(lastUpdateTime + effectiveTTL), re-armed on every store (create or
merge) — since 0.4.0. Reads and value-search listings never re-arm the
window. A continuously-updated document therefore persists indefinitely by
design (the producer owns the cache lifetime). A store targeting an
expired-but-salvageable document revives it.
The TTL hierarchy is Document > Document_Type > Instance (most specific
wins). TamaDB-Expire-At is an absolute, non-sliding, non-salvageable
deadline that overrides TTL.
Every store appends a timestamp entry to the stored document carrying a
Request_Timestamp (t1, request receipt — the versioning / history /
TTL-anchor time) and a Commit_Timestamp (t1+m, write-completion time).
As of 0.4.1 the Commit_Timestamp is populated on every stored entry
(it was previously always empty).
These timestamps are document metadata, not part of the default
retrieval response: GET /api/v1/documents/{documentType}/{dId} returns the
stored document's own fields (the producer payload plus any enrichment), and
the mode / path options only select which data fields are returned —
they never emit the metadata. Webhook deliveries do not carry it either:
the delivery body (see the webhook operation) is the document's content —
wrapped in delivery context only if the subscription asks for the
envelope format, with the context otherwise carried in TamaDB-* headers
— and never the stored timestamps. Delivering document metadata such as the
Commit_Timestamp to subscribers is planned for a later increment and is
not implemented yet; the includeMetadata subscription option is
accepted but currently has no effect.
All errors share a consistent shape (code + message, with optional
reason, context, quarantineRef, warning). See the Error schema and
the error-code → HTTP-status table in httpStatusForCode.
Returns ok plus build info (version, commit) and the active storage mode and log level. This is the only endpoint not under /api/v1.
| status required | any Always Value: "ok" |
| version required | string Resolved from package.json at runtime. |
| commit required | string Build commit; |
| storageMode required | string (StorageMode) Enum: "auto" "memory" "disk" "hybrid" The storage strategy governing where documents are held:
|
| logLevel required | string (LogLevel) Enum: "debug" "info" "warn" "error" "silent" The active log verbosity, most to least verbose:
|
{- "status": "ok",
- "version": "0.7.1",
- "commit": "5e1efe539201",
- "storageMode": "auto",
- "logLevel": "debug"
}Service-discovery metadata — stable identity, version/build fingerprint, environment, operational status, and where to find the docs — for humans and client tooling. Distinct from /health, which is the lightweight liveness/readiness probe. All values are resolved at runtime (from package.json / build-info) or from configuration (TAMADB_ENV, TAMADB_DOCS_URL, TAMADB_OPENAPI_URL), so a self-hosted instance can report its own environment and doc locations.
| name required | string Service/application name (from package.json). |
| description | string One-line service description (from package.json). |
| version required | string Current semantic version (from package.json), e.g. |
| commit required | string Build commit; |
| apiVersion required | string The URL contract version segment, e.g. |
| environment required | string Deployment stage label (configurable via |
| status required | string Operational state. |
| documentation required | string <uri> URL of the human-facing API reference (Redoc). |
| openapi required | string <uri> URL of the machine-readable OpenAPI document, for tooling discovery. |
| startedAt required | string <date-time> Process start time (ISO 8601), for a rough uptime signal. |
{- "name": "tamadb",
- "description": "TamaDB — a document-centric transmission cache for smart-endpoints/dumb-pipes architectures; a JSON document-oriented cache engine for producer/consumer data exchange (Increment 1).",
- "version": "0.7.1",
- "commit": "5e1efe539201",
- "apiVersion": "v1",
- "environment": "increment-1",
- "status": "operational",
- "startedAt": "2026-10-17T12:49:37.086Z"
}Responds 200 immediately, then (asynchronously) drains in-memory documents to disk, persists all component state, closes the HTTP server, and exits the process. The recommended cross-platform way to stop TamaDB (SIGTERM can be unreliable on some platforms). After the response, the server stops accepting new requests.
| status required | any Value: "shutting-down" |
{- "status": "shutting-down"
}Document ingestion. The request body is the bare JSON document; per-request instructions travel as reserved TamaDB-* Control_Headers.
Ingest a document for {documentType} via the default channel. The
request body is the bare JSON document (a JSON object), not a
wrapper. Per-request instructions are supplied as reserved TamaDB-*
Control_Headers (see parameters).
Returns 201 when the document is created and 200 when an existing
document is merged (upsert). On a payload-level rejection the response
carries an Error with an optional quarantineRef.
Each successful store records a timestamp entry on the stored document
with a populated Commit_Timestamp (write-completion time; see
Document metadata and timestamps). This metadata is not returned in
the ingest response — the response body is the IngestResult below.
| documentType required | string The Document_Type name. |
| TamaDB-Version | integer >= 1 Example: 2 Expected version number for optimistic concurrency — a positive integer (≥ 1). A mismatch is rejected with |
integer or "infinite" (string) Example: 3600 Document-level TTL — a non-negative integer number of seconds, or the literal | |
| TamaDB-Expire-At | string <date-time> Example: 2026-07-17T18:00:00Z Absolute expiry instant as an ISO-8601 / RFC 3339 date-time that must carry an explicit timezone (a trailing |
| TamaDB-Schema | string non-empty Example: temperature-sensor-v1 Explicit Storage_Schema override (a non-empty schema ref). This is the only way to override the schema per request — it is header-only. |
The bare JSON document — a JSON object, with no wrapper. A malformed body becomes a PARSE_ERROR and is quarantined per policy; a valid-JSON non-object is likewise a PARSE_ERROR.
| property name* additional property | any |
required | string or Array of strings (DId) |
| versionNo required | integer |
| created required | boolean True on create (201), false on merge (200). |
object |
required | string or Array of strings (DId) |
| versionNo required | integer |
| created required | boolean True on create (201), false on merge (200). |
object |
A complete reading sent to the default channel. The D-Id is extracted from the sensorId field (the primary-key).
{- "sensorId": "LIVING-ROOM-01",
- "location": "Living Room",
- "temperature": 21.5,
- "timestamp": "2026-07-17T10:05:00Z"
}{- "dId": "GARAGE-TEMP-01",
- "versionNo": 2,
- "created": false
}As POST /api/v1/ingest/{documentType}, but routes through the named {channelId} so channel enrichment and the channel schema apply.
| documentType required | string The Document_Type name. |
| channelId required | string The channel identifier. |
| TamaDB-Version | integer >= 1 Example: 2 Expected version number for optimistic concurrency — a positive integer (≥ 1). A mismatch is rejected with |
integer or "infinite" (string) Example: 3600 Document-level TTL — a non-negative integer number of seconds, or the literal | |
| TamaDB-Expire-At | string <date-time> Example: 2026-07-17T18:00:00Z Absolute expiry instant as an ISO-8601 / RFC 3339 date-time that must carry an explicit timezone (a trailing |
| TamaDB-Schema | string non-empty Example: temperature-sensor-v1 Explicit Storage_Schema override (a non-empty schema ref). This is the only way to override the schema per request — it is header-only. |
The bare JSON document — a JSON object, with no wrapper. A malformed body becomes a PARSE_ERROR and is quarantined per policy; a valid-JSON non-object is likewise a PARSE_ERROR.
| property name* additional property | any |
required | string or Array of strings (DId) |
| versionNo required | integer |
| created required | boolean True on create (201), false on merge (200). |
object |
required | string or Array of strings (DId) |
| versionNo required | integer |
| created required | boolean True on create (201), false on merge (200). |
object |
A complete reading sent to the default channel. The D-Id is extracted from the sensorId field (the primary-key).
{- "sensorId": "LIVING-ROOM-01",
- "location": "Living Room",
- "temperature": 21.5,
- "timestamp": "2026-07-17T10:05:00Z"
}{- "dId": "GARAGE-TEMP-01",
- "versionNo": 2,
- "created": false
}Retrieve a single document by {documentType} and {dId}.
If {dId} contains glob characters (* or ?), the endpoint switches
to glob retrieval and returns a { matches, count } collection
instead of a single document.
A TTL-expired but salvageable document is served in place as a Best-Effort Read (visibility only — the read does not re-arm the TTL, restore the document, or clear its soft-delete state).
| documentType required | string The Document_Type name. |
| dId required | string Examples:
The document identity. A composed D-Id joins its percent-encoded parts with the |
| path | string Field/sub-path projection (dotted path into the document). |
| mode | string Default: "full" Enum: "closed" "open" "full" Projection model controlling which fields the returned document
carries (default
|
| property name* additional property | any |
{- "sensorId": "GARAGE-TEMP-01",
- "location": "Garage",
- "temperature": 19.1,
- "timestamp": "2026-07-17T10:10:00Z"
}Soft-deletes the document with reason explicit. An explicit delete is permanent (non-salvageable) and is not revived by a later store.
| documentType required | string The Document_Type name. |
| dId required | string Examples:
The document identity. A composed D-Id joins its percent-encoded parts with the |
| deleted required | any Value: true |
| subscriptionsCancelled | integer >= 1 The number of D-Id-scoped subscriptions on this document that were auto-cancelled by the explicit delete. Present only when ≥1 subscription was cancelled; omitted when none were. Document_Type-scoped subscriptions are never cancelled by a document delete. |
{- "deleted": true
}Returns all documents of {documentType} whose field equals value.
includeExpired controls whether TTL-driven salvageable soft-deletes
are surfaced. It defaults to true when omitted. Search is
visibility-only: it never alters the TTL clock or persists a state
change. A document listed by search is not guaranteed retrievable by
a later point lookup.
| documentType required | string The Document_Type name. |
| field required | string The field name (or path) to match on. |
| value required | any The value to match (any JSON type). |
| includeExpired | boolean Default: true Whether TTL-driven, salvageable soft-deleted documents are surfaced in the results (visibility only — never alters the TTL clock or persists a state change):
Non-salvageable soft-deletes ( |
required | Array of objects (Document) |
| count required | integer |
{- "field": "location",
- "value": "Garage"
}{- "matches": [
- {
- "sensorId": "GARAGE-TEMP-01",
- "location": "Garage",
- "temperature": 19.1,
- "timestamp": "2026-07-17T10:10:00Z"
}
], - "count": 1
}Sets the document-level TTL — the most specific rung of the TTL hierarchy (Document > Document_Type > Instance). A TTL below the configured floor is raised to the floor and reported via warning.
| documentType required | string The Document_Type name. |
| dId required | string Examples:
The document identity. A composed D-Id joins its percent-encoded parts with the |
required | integer or "infinite" (string) (Ttl) |
| documentType required | string |
| dId required | string |
required | integer or "infinite" (string) (Ttl) |
object (TtlWarning) Emitted when a requested TTL was raised to the configured floor. |
{- "ttl": 7200
}{- "documentType": "temperature-readings",
- "dId": "GARAGE-TEMP-01",
- "ttl": 7200
}Register a JSON Schema under a unique ref. The schema may carry
identityKind annotations (primary-key / parent-key) on scalar leaf
properties to drive D-Id extraction; those annotations are ignored by
validation. An optional dIdDefinition provides a metadata fallback for
third-party schemas that cannot be annotated inline.
| ref required | string Unique schema reference. |
required | object (JsonSchema) A JSON Schema document. May carry the TamaDB-specific |
object (DIdDefinition) Metadata fallback D-Id definition for schemas not annotated inline. |
| ref required | string |
| version required | integer |
{- "ref": "temperature-sensor-v1",
- "schema": {
- "type": "object",
- "properties": {
- "sensorId": {
- "type": "string",
- "identityKind": "primary-key"
}, - "location": {
- "type": "string"
}, - "temperature": {
- "type": "number"
}, - "timestamp": {
- "type": "string"
}
}, - "required": [
- "sensorId",
- "location",
- "temperature"
]
}
}{- "ref": "temperature-sensor-v1",
- "version": 1
}Returns every registered schema entry. Symmetric with GET /api/v1/config/document-types. Added in 0.5.0.
| ref required | string |
required | object (JsonSchema) A JSON Schema document. May carry the TamaDB-specific |
| version required | integer |
required | Array of objects (SchemaVersion) |
| lifecycle required | string Enum: "active" "decommissioned" Schema lifecycle state:
|
object (DIdDefinition) Metadata fallback D-Id definition for schemas not annotated inline. | |
| createdAt required | string <date-time> |
| updatedAt required | string <date-time> |
[- {
- "ref": "temperature-sensor-v1",
- "schema": {
- "type": "object",
- "properties": {
- "sensorId": {
- "type": "string",
- "identityKind": "primary-key"
}
}, - "required": [
- "sensorId"
]
}, - "version": 1,
- "versions": [
- {
- "version": 1,
- "schema": {
- "type": "object"
}, - "timestamp": "2026-07-17T09:00:00Z"
}
], - "lifecycle": "active",
- "createdAt": "2026-07-17T09:00:00Z",
- "updatedAt": "2026-07-17T09:00:00Z"
}
]| schemaRef required | string The schema reference. |
| ref required | string |
required | object (JsonSchema) A JSON Schema document. May carry the TamaDB-specific |
| version required | integer |
required | Array of objects (SchemaVersion) |
| lifecycle required | string Enum: "active" "decommissioned" Schema lifecycle state:
|
object (DIdDefinition) Metadata fallback D-Id definition for schemas not annotated inline. | |
| createdAt required | string <date-time> |
| updatedAt required | string <date-time> |
{- "ref": "temperature-sensor-v1",
- "schema": {
- "type": "object",
- "properties": {
- "sensorId": {
- "type": "string",
- "identityKind": "primary-key"
}, - "location": {
- "type": "string"
}, - "temperature": {
- "type": "number"
}, - "timestamp": {
- "type": "string"
}
}, - "required": [
- "sensorId",
- "location",
- "temperature"
]
}, - "version": 1,
- "versions": [
- {
- "version": 1,
- "schema": {
- "type": "object"
}, - "timestamp": "2026-07-17T09:00:00Z"
}
], - "lifecycle": "active",
- "createdAt": "2026-07-17T09:00:00Z",
- "updatedAt": "2026-07-17T09:00:00Z"
}| schemaRef required | string The schema reference. |
required | object (JsonSchema) A JSON Schema document. May carry the TamaDB-specific |
| ref required | string |
| version required | integer |
{- "schema": {
- "type": "object",
- "properties": {
- "sensorId": {
- "type": "string",
- "identityKind": "primary-key"
}, - "location": {
- "type": "string"
}, - "temperature": {
- "type": "number"
}, - "humidity": {
- "type": "number"
}, - "timestamp": {
- "type": "string"
}
}, - "required": [
- "sensorId",
- "location",
- "temperature"
]
}
}{- "ref": "temperature-sensor-v1",
- "version": 2
}Rejected while the schema is the Master_Schema of an active Document_Type (MASTER_SCHEMA_ACTIVE).
| schemaRef required | string The schema reference. |
| decommissioned required | any Value: true |
{- "decommissioned": true
}| schemaRef required | string The schema reference. |
| version required | integer |
required | object (JsonSchema) A JSON Schema document. May carry the TamaDB-specific |
| timestamp required | string <date-time> |
[- {
- "version": 1,
- "schema": {
- "type": "object"
}, - "timestamp": "2026-07-17T09:00:00Z"
}, - {
- "version": 2,
- "schema": {
- "type": "object"
}, - "timestamp": "2026-07-17T09:30:00Z"
}
]| name required | string |
| masterSchema required | string Ref of the registered Master_Schema. |
| model required | string (DocumentModel) Enum: "closed" "hybrid" "open" The validation model for a Document_Type:
|
integer or "infinite" (string) (Ttl) |
| name required | string |
| masterSchema required | string |
| model required | string (DocumentModel) Enum: "closed" "hybrid" "open" The validation model for a Document_Type:
|
integer or "infinite" (string) (Ttl) | |
| channels | Array of strings Channel IDs registered against this Document_Type. |
| createdAt | string <date-time> |
| updatedAt | string <date-time> |
{- "name": "temperature-readings",
- "masterSchema": "temperature-sensor-v1",
- "model": "closed",
- "ttl": 3600
}{- "name": "temperature-readings",
- "masterSchema": "temperature-sensor-v1",
- "model": "closed",
- "ttl": 3600,
- "channels": [ ],
- "createdAt": "2026-07-17T09:05:00Z",
- "updatedAt": "2026-07-17T09:05:00Z"
}| name required | string |
| masterSchema required | string |
| model required | string (DocumentModel) Enum: "closed" "hybrid" "open" The validation model for a Document_Type:
|
integer or "infinite" (string) (Ttl) | |
| channels | Array of strings Channel IDs registered against this Document_Type. |
| createdAt | string <date-time> |
| updatedAt | string <date-time> |
[- {
- "name": "temperature-readings",
- "masterSchema": "temperature-sensor-v1",
- "model": "closed",
- "ttl": 3600,
- "channels": [
- "garage-sensor"
], - "createdAt": "2026-07-17T09:05:00Z",
- "updatedAt": "2026-07-17T09:05:00Z"
}
]| documentType required | string The Document_Type name. |
| name required | string |
| masterSchema required | string |
| model required | string (DocumentModel) Enum: "closed" "hybrid" "open" The validation model for a Document_Type:
|
integer or "infinite" (string) (Ttl) | |
| channels | Array of strings Channel IDs registered against this Document_Type. |
| createdAt | string <date-time> |
| updatedAt | string <date-time> |
{- "name": "temperature-readings",
- "masterSchema": "temperature-sensor-v1",
- "model": "closed",
- "ttl": 3600,
- "channels": [
- "garage-sensor"
], - "createdAt": "2026-07-17T09:05:00Z",
- "updatedAt": "2026-07-17T09:05:00Z"
}Rejected while documents of that type exist (including soft-deleted ones) — DOCUMENTS_EXIST.
| documentType required | string The Document_Type name. |
| deleted required | any Value: true |
{- "deleted": true
}| documentType required | string The Document_Type name. |
required | integer or "infinite" (string) (Ttl) |
required | integer or "infinite" (string) (Ttl) |
object (TtlWarning) Emitted when a requested TTL was raised to the configured floor. |
{- "ttl": 7200
}{- "ttl": 7200
}Returns the governing TTL the TtlManager actually consults for a type — the Document_Type TTL, or the instance TTL if none is configured for the type. Symmetric with GET /api/v1/config/ttl/instance.
| documentType required | string The Document_Type name. |
| documentType required | string |
required | integer or "infinite" (string) (Ttl) |
{- "documentType": "temperature-readings",
- "ttl": 3600
}| channelId required | string |
| documentType required | string |
| channelSchema | string Optional Channel_Schema ref. |
| initialStatus | string Enum: "active" "inactive" The channel's status at registration (default
|
| channelId required | string |
| documentType required | string |
| channelSchema | string or null |
Array of objects (EnrichmentBinding) | |
| status required | string Enum: "active" "inactive" "blocked" Channel status:
|
| endpoint | string The ingest URL path for this channel. |
{- "channelId": "garage-sensor",
- "documentType": "temperature-readings",
- "channelSchema": "temperature-sensor-v1"
}{- "channelId": "garage-sensor",
- "documentType": "temperature-readings",
- "channelSchema": "temperature-sensor-v1",
- "enrichmentBindings": [ ],
- "status": "active",
- "endpoint": "/api/v1/ingest/temperature-readings/garage-sensor"
}| documentType | string Filter channels by Document_Type. |
| channelId required | string |
| documentType required | string |
| channelSchema | string or null |
Array of objects (EnrichmentBinding) | |
| status required | string Enum: "active" "inactive" "blocked" Channel status:
|
| endpoint | string The ingest URL path for this channel. |
[- {
- "channelId": "garage-sensor",
- "documentType": "temperature-readings",
- "channelSchema": "temperature-sensor-v1",
- "enrichmentBindings": [
- {
- "fieldPath": "sensorId",
- "staticValue": "GARAGE-TEMP-01"
}, - {
- "fieldPath": "location",
- "staticValue": "Garage"
}
], - "status": "active",
- "endpoint": "/api/v1/ingest/temperature-readings/garage-sensor"
}
]| channelId required | string The channel identifier. |
| channelSchema | string or null New Channel_Schema ref, or null to clear. |
| channelId required | string |
| documentType required | string |
| channelSchema | string or null |
Array of objects (EnrichmentBinding) | |
| status required | string Enum: "active" "inactive" "blocked" Channel status:
|
| endpoint | string The ingest URL path for this channel. |
{- "channelSchema": "temperature-sensor-v1"
}{- "channelId": "garage-sensor",
- "documentType": "temperature-readings",
- "channelSchema": "temperature-sensor-v1",
- "enrichmentBindings": [ ],
- "status": "active",
- "endpoint": "/api/v1/ingest/temperature-readings/garage-sensor"
}Each binding sets a static value at a field path during ingestion. dIdClassification reports whether any binding targets an identityKind-annotated field (foreign) or not (native).
| channelId required | string The channel identifier. |
required | Array of objects (EnrichmentBinding) |
| registered required | any Value: true |
| dIdClassification required | string Enum: "native" "foreign" Whether any registered binding targets a D-Id
(
|
{- "bindings": [
- {
- "fieldPath": "sensorId",
- "staticValue": "GARAGE-TEMP-01"
}, - {
- "fieldPath": "location",
- "staticValue": "Garage"
}
]
}{- "registered": true,
- "dIdClassification": "native"
}| channelId required | string The channel identifier. |
| fieldPath required | string |
| staticValue required | any The static value injected at |
[- {
- "fieldPath": "sensorId",
- "staticValue": "GARAGE-TEMP-01"
}, - {
- "fieldPath": "location",
- "staticValue": "Garage"
}
]TamaDB → subscriber (not a request you make). When a store writes a
subscribed node, TamaDB POSTs the delivery to the subscription's
callbackUrl.
Body. By default (payloadFormat: raw) the body is exactly the
document content you asked for — shaped by the subscription's
retrievalSchema when retrievalMode is closed — with no TamaDB
wrapper. With payloadFormat: envelope the same content is wrapped in
delivery context. See SubscriptionOptions.
Headers. Every delivery, in either format, carries TamaDB's delivery
context as the TamaDB-* HTTP headers below, so the body never has to.
The Document_Type, D-Id and path values are percent-encoded exactly as
in URL path segments: split a composed D-Id on the delimiter (default
:) first, then decode each part.
Envelope fields. With payloadFormat: envelope the same context is
also in the body, under the field names below. Every envelope field has a
header equivalent carrying the same value, except where noted:
| Envelope field | Header | Notes |
|---|---|---|
subscriptionId |
TamaDB-Subscription-Id |
Identical. |
documentType |
TamaDB-Document-Type |
The header is percent-encoded. |
dId |
TamaDB-D-Id |
Envelope: a string, or an array of strings for a composed D-Id. Header: URL form, e.g. ORD-1001:L-1 (percent-encoded parts joined by :). |
path |
TamaDB-Path |
Node-scoped subscriptions only. The header is percent-encoded. |
timestamp |
TamaDB-Enqueued-At |
The same instant: when the delivery snapshot was captured. A delivery time, not a stored document timestamp, and unrelated to any timestamp field inside document. |
document |
none | The projected document content. In raw format this is the whole body. |
Delivery is snapshot-at-enqueue and governed by the subscription's
delivery mode: fire-and-forget (a single attempt) or retry (bounded
exponential backoff). A retry re-sends the identical body and headers.
Your endpoint SHOULD respond 2xx to acknowledge; any non-2xx, timeout,
or connection error is treated as a failed attempt.
| TamaDB-Subscription-Id required | string Example: sub-mv65oc4u-0002 The subscription that matched the write. |
| TamaDB-Document-Type required | string Example: temperature-readings The Document_Type of the written document, percent-encoded. |
| TamaDB-D-Id required | string Example: GARAGE-TEMP-01 The written document's identity in URL form: a single key as-is, or a composed key as its percent-encoded parts joined by the delimiter (default |
| TamaDB-Enqueued-At required | string <date-time> Example: 2026-11-10T22:27:58.540Z When the delivery snapshot was captured (UTC, millisecond precision). This is a delivery time, not the document's own stored timestamps. |
| TamaDB-Path | string Example: temperature Present only when the subscription is node-scoped: the percent-encoded dot-notation leaf or bunch path it targets. |
The delivery body. raw (the default) is the document content itself; envelope wraps it with delivery context.
| property name* additional property | any |
{- "sensorId": "GARAGE-TEMP-01",
- "temperature": 22,
- "humidity": 40
}Subscribe to document events by document_type or document_id scope. When scope is document_id, provide dId.
| scope required | string Enum: "document_type" "document_id" What the subscription watches:
|
| documentType required | string |
| dId | string Required when scope is |
| callbackUrl required | string <uri> |
| path | string Optional node-scoped target: a dot-notation leaf or bunch path. When present, the subscription fires only when a store writes that node (or, for a bunch path, any leaf within it) — not on every write to the document. Triggering is presence-in-write and content-agnostic: it does not depend on whether the written value changed. |
object (SubscriptionOptions) Per-subscription delivery options. All fields are optional on create; omitted fields take the defaults shown. The server returns the fully resolved set (defaults filled in) on the subscription record. |
| id required | string Server-assigned subscription identifier. |
| scope required | string Enum: "document_type" "document_id"
|
| documentType required | string |
string or Array of strings (DId) | |
| callbackUrl required | string <uri> |
| path | string Node-scoped target: a dot-notation leaf or bunch path. Present on a |
object The fully resolved delivery options (defaults filled in). See | |
| createdAt | string <date-time> |
| active | boolean |
{- "scope": "document_type",
- "documentType": "temperature-readings",
- "options": {
- "payloadFormat": "envelope",
- "retrievalMode": "closed",
- "retrievalSchema": {
- "properties": {
- "temperature": {
- "type": "number"
}
}
}, - "deliveryMode": "retry"
}
}{- "id": "sub-muu900km-0001",
- "scope": "document_type",
- "documentType": "temperature-readings",
- "options": {
- "retrievalMode": "full",
- "schemaAdoptionMode": "pinned",
- "payloadFormat": "raw",
- "includeMetadata": false,
- "deliveryMode": "fire-and-forget"
}, - "createdAt": "2026-07-17T10:15:00Z",
- "active": true
}| documentType required | string The Document_Type name. |
| dId required | string Examples:
The document identity. A composed D-Id joins its percent-encoded parts with the |
| id required | string Server-assigned subscription identifier. |
| scope required | string Enum: "document_type" "document_id"
|
| documentType required | string |
string or Array of strings (DId) | |
| callbackUrl required | string <uri> |
| path | string Node-scoped target: a dot-notation leaf or bunch path. Present on a |
object The fully resolved delivery options (defaults filled in). See | |
| createdAt | string <date-time> |
| active | boolean |
[- {
- "id": "sub-mv65oc4u-0002",
- "scope": "document_id",
- "documentType": "temperature-readings",
- "dId": "GARAGE-TEMP-01",
- "options": {
- "retrievalMode": "full",
- "schemaAdoptionMode": "pinned",
- "payloadFormat": "raw",
- "includeMetadata": false,
- "deliveryMode": "fire-and-forget"
}, - "createdAt": "2026-07-17T10:16:00Z",
- "active": true
}
]| documentType required | string The Document_Type name. |
| id required | string Server-assigned subscription identifier. |
| scope required | string Enum: "document_type" "document_id"
|
| documentType required | string |
string or Array of strings (DId) | |
| callbackUrl required | string <uri> |
| path | string Node-scoped target: a dot-notation leaf or bunch path. Present on a |
object The fully resolved delivery options (defaults filled in). See | |
| createdAt | string <date-time> |
| active | boolean |
[- {
- "id": "sub-mv65ntlh-0001",
- "scope": "document_type",
- "documentType": "temperature-readings",
- "options": {
- "retrievalMode": "full",
- "schemaAdoptionMode": "pinned",
- "payloadFormat": "raw",
- "includeMetadata": false,
- "deliveryMode": "fire-and-forget"
}, - "createdAt": "2026-07-17T10:15:00Z",
- "active": true
}
]| rejectionType | string Enum: "parse-error" "validation-failure" "enrichment-conflict" Filter by why the payload was quarantined (the same value set as a
quarantine entry's
|
| sourceIdentifier | string Filter by the ingestion source identifier (e.g. channel). |
| limit | integer >= 0 |
| offset | integer >= 0 |
required | Array of objects (QuarantineEntry) |
| count required | integer |
{- "entries": [
- {
- "ref": "qr-muu900r6-0001",
- "payload": {
- "sensorId": "BAD-1",
- "location": "X",
- "temperature": "not-a-number",
- "extra": "nope"
}, - "context": {
- "receivedAt": "2026-07-17T10:20:00Z",
- "sourceIdentifier": "default",
- "schemaRef": "temperature-sensor-v1",
- "rejectionReason": "/extra: Field 'extra' is not defined in the schema (DCM: no extensions allowed); /temperature: must be number",
- "rejectionType": "validation-failure",
- "controlHeaders": { }
}
}
], - "count": 1
}| quarantineRef required | string |
| ref | string Quarantine reference (the quarantineRef returned on rejection). |
| payload | any The rejected payload (as received). |
object |
{- "ref": "qr-muu900r6-0001",
- "payload": {
- "sensorId": "BAD-1",
- "location": "X",
- "temperature": "not-a-number",
- "extra": "nope"
}, - "context": {
- "receivedAt": "2026-07-17T10:20:00Z",
- "sourceIdentifier": "default",
- "schemaRef": "temperature-sensor-v1",
- "rejectionReason": "/extra: Field 'extra' is not defined in the schema (DCM: no extensions allowed); /temperature: must be number",
- "rejectionType": "validation-failure",
- "controlHeaders": { }
}
}required | integer or "infinite" (string) (Ttl) |
required | integer or "infinite" (string) (Ttl) |
object (TtlWarning) Emitted when a requested TTL was raised to the configured floor. |
{- "ttl": 1800
}{- "ttl": 1800
}| interval required | integer Sweep interval in milliseconds. |
| sweepInterval required | integer |
{- "interval": 60000
}{- "sweepInterval": 60000
}| mode required | string (StorageMode) Enum: "auto" "memory" "disk" "hybrid" The storage strategy governing where documents are held:
|
{- "mode": "memory"
}| mode required | string (StorageMode) Enum: "auto" "memory" "disk" "hybrid" The storage strategy governing where documents are held:
|
| mode required | string (StorageMode) Enum: "auto" "memory" "disk" "hybrid" The storage strategy governing where documents are held:
|
{- "mode": "hybrid"
}{- "mode": "hybrid"
}| policy required | string (QuarantinePolicyValue) Enum: "off" "data-errors-only" "all-rejections" Which rejected ingests are captured in quarantine:
|
{- "policy": "data-errors-only"
}| policy required | string (QuarantinePolicyValue) Enum: "off" "data-errors-only" "all-rejections" Which rejected ingests are captured in quarantine:
|
| policy required | string (QuarantinePolicyValue) Enum: "off" "data-errors-only" "all-rejections" Which rejected ingests are captured in quarantine:
|
{- "policy": "all-rejections"
}{- "policy": "all-rejections"
}| precedence | string Enum: "environment-over-content" "content-over-environment" Who wins when a channel enrichment binding and the producer payload both set the same field:
|
| conflictResolution | string Enum: "accept-and-warn" "discard-and-error" What happens on an enrichment conflict:
|
{- "precedence": "environment-over-content",
- "conflictResolution": "accept-and-warn"
}| precedence | string Enum: "environment-over-content" "content-over-environment" Who wins when a channel enrichment binding and the producer payload both set the same field:
|
| conflictResolution | string Enum: "accept-and-warn" "discard-and-error" What happens on an enrichment conflict:
|
| precedence | string Enum: "environment-over-content" "content-over-environment" Who wins when a channel enrichment binding and the producer payload both set the same field:
|
| conflictResolution | string Enum: "accept-and-warn" "discard-and-error" What happens on an enrichment conflict:
|
{- "precedence": "content-over-environment"
}{- "precedence": "content-over-environment",
- "conflictResolution": "accept-and-warn"
}| level | string (LogLevel) Enum: "debug" "info" "warn" "error" "silent" The active log verbosity, most to least verbose:
|
| destination | string (LogDestination) Enum: "stdout" "file" "none" Where log output is written:
|
| filePath | string Target file path; present/relevant when |
| property name* additional property | any |
{- "level": "warn",
- "destination": "stdout"
}| level required | string (LogLevel) Enum: "debug" "info" "warn" "error" "silent" The active log verbosity, most to least verbose:
|
| level | string (LogLevel) Enum: "debug" "info" "warn" "error" "silent" The active log verbosity, most to least verbose:
|
| destination | string (LogDestination) Enum: "stdout" "file" "none" Where log output is written:
|
| filePath | string Target file path; present/relevant when |
| property name* additional property | any |
{- "level": "info"
}{- "level": "info",
- "destination": "stdout"
}| level | string (LogLevel) Enum: "debug" "info" "warn" "error" "silent" The active log verbosity, most to least verbose:
|
| destination | string (LogDestination) Enum: "stdout" "file" "none" Where log output is written:
|
| filePath | string Target file path; present/relevant when |
| property name* additional property | any |
{- "level": "info",
- "destination": "stdout"
}| destination required | string (LogDestination) Enum: "stdout" "file" "none" Where log output is written:
|
| filePath | string Required when destination is |
| level | string (LogLevel) Enum: "debug" "info" "warn" "error" "silent" The active log verbosity, most to least verbose:
|
| destination | string (LogDestination) Enum: "stdout" "file" "none" Where log output is written:
|
| filePath | string Target file path; present/relevant when |
| property name* additional property | any |
{- "destination": "stdout"
}{- "level": "info",
- "destination": "stdout"
}