Configuration

Runtime configuration endpoints. All settings are changeable without restarting TamaDB.

Quick Reference

Method	Path	Summary
GET	/api/v1/config/log-level	Get current log level
PUT	/api/v1/config/log-level	Change log level
GET	/api/v1/config/log-destination	Get current log destination
PUT	/api/v1/config/log-destination	Change log destination
GET	/api/v1/config/storage-strategy	Get current storage strategy
PUT	/api/v1/config/storage-strategy	Change storage strategy
POST	/api/v1/config/storage/drain	Drain memory to disk
GET	/api/v1/config/quarantine-policy	Get quarantine policy
PUT	/api/v1/config/quarantine-policy	Change quarantine policy
GET	/api/v1/config/enrichment-policies	Get enrichment policies
PUT	/api/v1/config/enrichment-policies	Change enrichment policies
GET	/api/v1/config/ttl/instance	Get instance-level TTL
PUT	/api/v1/config/ttl/instance	Set instance-level TTL
PUT	/api/v1/config/ttl/sweep-interval	Set TTL sweep interval

GET PUT

/api/v1/config/log-level

Get or change the current log level.

PUT Request Body

{
  "level": "debug"|"info"|"warn"|"error"|"silent"
}

Response

200 OK 400 Bad Request (invalid level)

{
  "level": "warn"
}

GET PUT

/api/v1/config/log-destination

Get or change the log output destination.

PUT Request Body

Field	Type	Required	Description
destination	string	Yes	`"stdout"` \| `"file"` \| `"none"`
filePath	string	Conditional	Required when destination is `"file"`

Response

200 OK 400 Bad Request

{
  "destination": "file",
  "filePath": "./tamadb.log"
}

Note: When destination is "stdout" or "none", the filePath field is omitted from the response. When destination is "file", filePath is required in the request.

GET PUT

/api/v1/config/storage-strategy

Get or change the storage strategy.

PUT Request Body

{
  "mode": "auto"|"memory"|"disk"|"hybrid"
}

Response

200 OK 400 Bad Request

{
  "mode": "memory"
}

POST

/api/v1/config/storage/drain

Flush all in-memory documents to disk. No-op when already in disk mode.

Request Body

No request body required.

Response

200 OK

{
  "drained": true,
  "documentsWritten": 42,
  "mode": "auto"
}

Note: Flushes all in-memory documents to disk. No-op in disk mode. Also runs automatically on graceful shutdown (Ctrl+C / SIGTERM).

GET PUT

/api/v1/config/quarantine-policy

Get or change the quarantine policy.

PUT Request Body

{
  "policy": "off"|"data-errors-only"|"all-rejections"
}

Response

200 OK 400 Bad Request

{
  "policy": "all-rejections"
}

GET PUT

/api/v1/config/enrichment-policies

Get or change enrichment policies that control how environment metadata merges with document content.

PUT Request Body

Field	Type	Required	Description
precedence	string	Yes	`"environment-over-content"` \| `"content-over-environment"`
conflictResolution	string	Yes	`"accept-and-warn"` \| `"discard-and-error"`

Response

200 OK 400 Bad Request

{
  "precedence": "environment-over-content",
  "conflictResolution": "accept-and-warn"
}

GET PUT

/api/v1/config/ttl/instance

Get or set the instance-level TTL (time-to-live) for documents.

PUT Request Body

{
  "ttl": 3600  // number (seconds) or "infinite"
}

Value 0 = transient (immediate expiry). "infinite" = no expiry.

Response

200 OK 400 Bad Request

{
  "ttl": 7200
}

Note: Applies to documents without a more specific (Document_Type or per-document) TTL.

PUT

/api/v1/config/ttl/sweep-interval

Set how frequently TamaDB checks for expired documents.

Request Body

{
  "interval": 30000  // milliseconds
}

Response

200 OK 400 Bad Request

{
  "interval": 30000
}

Note: Controls how frequently TamaDB checks for expired documents. Value is in milliseconds.