get_retention

GET

/api/v1/settings/retention

curl --request GET \
  --url https://example.com/api/v1/settings/retention \
  --header 'Authorization: Bearer <token>'

Authorizations

• bearer

Responses

200

The deployment’s retention policy: editable windows plus the full table, including rows set by a store’s own start flag

Media typeapplication/json

The full retention policy: the editable windows plus every row of the table.

object

rows

required

Every retained subject, including the ones no API can change.

Array<object>

One line of the retention table.

object

enforcement

required

How the window is applied: pg_prune, store_ttl, store_flag or unlimited.

string

field

required

Which field of settings this row binds to, or store_owned / unlimited.

string

note

required

Operator-facing explanation. For a read-only row it names the flag that does change it.

string

store

required

The store that holds it.

string

store_configured

required

Whether the backing store is configured in this deployment. A row for an unconfigured optional store retains nothing.

boolean

store_reported

What the store itself reports for a store_flag row, verbatim (e.g. 12, 30d). Absent when the store is unreachable or is running its own default — in which case the value is genuinely unknown and is not guessed.

string | null

subject

required

Stable identifier for the retained data, e.g. alert_history.

string

tunable

required

Where it can be changed: settings (here), store_flag_read_only (the store’s own command-line flag), or by_decision (not retained on a schedule at all).

string

unit

required

Unit of value: days, hours, or empty when the row has no configurable number.

string

value

The configured window, for rows this deployment controls.

integer | null format: int32

settings

required

The windows this endpoint can change.

object

alert_linked_days

required

Days to keep alert history, node-state snapshots, DNS chain changes and matched events.

integer format: int32

diagnostic_days

Days to keep on-demand diagnostics: Troubleshoot analysis runs with their findings, and generated AI root-cause reports. Optional — omitting it sets the default (90).

integer format: int32

flow_days

required

Days to keep traffic-flow records, applied as a ClickHouse table TTL.

integer format: int32

report_run_days

required

Days to keep generated report runs.

integer format: int32

unmatched_event_hours

required

Hours to keep passive events that matched no rule.

integer format: int32

Example^generated

{
  "rows": [
    {
      "enforcement": "example",
      "field": "example",
      "note": "example",
      "store": "example",
      "store_configured": true,
      "store_reported": "example",
      "subject": "example",
      "tunable": "example",
      "unit": "example",
      "value": 1
    }
  ],
  "settings": {
    "alert_linked_days": 1,
    "diagnostic_days": 1,
    "flow_days": 1,
    "report_run_days": 1,
    "unmatched_event_hours": 1
  }
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks View

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Inventory storage is unavailable (skeleton mode)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}