Reference
The tables on this page follow the technical reference in the source (core/README.md).
Record types
Section titled “Record types”POST /v1/ingest, bearer token with the role ingest, the body a JSON array or NDJSON. At most 1 MiB and 1000 records; a batch applies completely or not at all. Unknown fields are rejected.
Every record has type, thing (an id you choose: letters, digits and . _ : @ -) and optionally ts.
| Type | Fields | Meaning |
|---|---|---|
thing | kind, name, labels, url, price{amount, currency, per, side, until}, expect_s, gone | Describes a thing. Only the fields you send change. price.per is hour, day, month or year. price.side is cost (the default) or revenue. price.until is where the amount ends by itself: a depreciation, a contract with a term. expect_s: “I report on this at least this often” — silence beyond it is critical. gone: it no longer exists; it stops costing and its episodes resolve. |
state | check, status (ok/warn/crit), summary, due, vars, ttl_s, amount + currency, side | The state of one named check, as this source sees it. Reported past its due date and not ok, it has needed someone since that date, not since now. With an amount it is also something outstanding: owed to you (side revenue) or by you (cost, the default) until this source reports the state without an amount. ttl_s: how long the report counts when several sources report the same check. |
event | event, outcome (ok/fail/absent), summary, vars, amount + currency, or quantity, side | Something happened. With an outcome it is a run: a failure turns the check of the same name critical until a run succeeds. An event may carry what it cost (amount), or a quantity that an event price in the configuration turns into a cost. |
metric | metric, value | A number. Kept as the last value plus a one-day ring, compared against threshold rules. |
cost | amount, currency, from, to | What the thing cost in a period. Sending the same period again replaces it. |
revenue | amount, currency, from, to | What the thing brought in a period; otherwise like cost. |
edge | rel (part_of/runs_on/depends_on), target, gone | Costs roll up along part_of. An episode on a thing whose runs_on/depends_on target is critical is shown under its cause and notifies nobody. |
A thing’s first price counts from the record’s ts (now, if it has none). A later change of the price counts from the moment it is reported.
When several sources report the same check, the check’s state is the second-worst report, and at least warn while any source is unhappy.
Bearer token with the role read or operate.
| Endpoint | Returns |
|---|---|
GET /v1/attention?thing= | open episodes (critical first, consequences last) and checks coming due within 30 days — for everything, or for one scope |
GET /v1/ledger?thing= | the Ledger Line as data: the verdict, the episode to name first, thirty past days, what comes due in the next thirty, and the month’s cost and revenue so far and in total |
GET /v1/things?kind= | things with their worst status |
GET /v1/things/{id} | one thing: states, episodes, events, edges, metrics with samples |
GET /v1/scopes | every thing that something is part of, with how many things it covers and the worst open episode in it |
GET /v1/costs?from=&to= | own and rolled-up cost per thing and totals per currency; the default is the whole current month |
GET /v1/money?from=&to=&thing= | cost and revenue per thing, own and rolled up, and what is outstanding now, soonest due first |
GET /v1/top?from=&to= | three short lists for a period: what needed attention most, cost most, brought most |
GET /v1/review?from=&to=&thing= | a period looked back on: what came back, whether fixes held, noise, what was done late, and all of it as one Brief (brief) |
GET /v1/episodes?from=&to=&thing= | the episodes that were open in a period (default: the last 30 days) and, per day, the worst of them |
GET /v1/episodes/{id} | one episode |
GET /v1/episodes/{id}/actions | the matching Brief templates, rendered for this episode |
POST /v1/episodes/{id}/actions/{action} | queue a webhook Brief (role operate) |
POST /mcp | the read-only MCP server; see the Brief |
Placeholders in a Brief
Section titled “Placeholders in a Brief”| Placeholder | Becomes |
|---|---|
{{thing.id}}, {{thing.name}}, {{thing.kind}}, {{thing.url}} | the thing |
{{check}}, {{status}}, {{summary}}, {{started}}, {{episode}} | the episode |
{{due}} | the due date |
{{amount}}, {{side}} | what the check carries as outstanding (“2400.00 USD”), and on which side |
{{vars.KEY}}, {{labels.KEY}} | what the source sent along, and the thing’s labels |
{{history}} | whether this happened before, when, for how long |
{{follows}} | what is open only because of it |
{{last_fix}} | what helped the last time |
{{events}} | the thing’s last five events |
{{context}} | all four of the above |
Nothing else is substituted.
Configuration
Section titled “Configuration”Every *.json file in NOTA_CONF may hold these keys; the files are merged.
| Key | What it holds |
|---|---|
rules | threshold (a metric beyond warn/crit for for_s seconds) or expect (a successful event at least every every_s seconds), scoped by kind or thing |
actions | Brief templates: prompt (a text to copy) or webhook (the same text posted to url) |
notify | targets, webhook or ntfy, with min_status |
digest | the morning sentence: {"at": "07:30", "tz": "Europe/Berlin"} |
things | things declared by hand, above all what they cost: id, kind, name, labels, url, part_of, price, since |
event_prices | what an event costs when it does not carry an amount itself: amount for every per units of the event’s quantity, matched by event and optionally kind or thing |
A declared price counts from the moment it is first declared, or from since (2026-01-01) for something that was always there. A thing taken out of the configuration stops costing from then on; it is not removed.
The rules that ship:
{ "rules": [ {"id": "disk-full", "type": "threshold", "kind": "server", "metric": "disk_used_ratio", "warn": 0.8, "crit": 0.92, "for_s": 600, "check": "disk"}, {"id": "memory-low", "type": "threshold", "kind": "server", "metric": "memory_available_ratio", "op": "<", "warn": 0.1, "crit": 0.04, "for_s": 600, "check": "memory"}, {"id": "load-high", "type": "threshold", "kind": "server", "metric": "load5_per_cpu", "warn": 1.5, "crit": 3, "for_s": 900, "check": "load"}, {"id": "backup-daily", "type": "expect", "kind": "backup", "event": "run", "every_s": 93600}, {"id": "job-hourly", "type": "expect", "kind": "hourly-job", "event": "run", "every_s": 4500} ]}Columns of a list
Section titled “Columns of a list”| Column | German name | Meaning |
|---|---|---|
thing | ding | id of the thing the row is about; a row without one continues the row above |
name, kind, part_of | name, art, teil_von | describe the thing; part_of rolls its money up |
check | aufgabe | what is due — with it the row is a deadline |
due | fällig | when |
every | alle | month, quarter, year: the deadline recurs |
done | erledigt | the date it was done |
warn_days | warn_tage | warn this many days before it is due (default: on the day) |
crit_days | krit_tage | critical this many days after it was due (default: never) |
amount, currency, side | betrag, währung, seite | with a check: what is outstanding, owed by you (cost, the default) or to you (revenue); without a check and with per: what the thing costs or brings |
per | je | hour, day, month, year: a recurring amount |
since, until | seit, bis | from when the recurring amount counts, and where it ends |
summary | text | a sentence shown with the deadline — for a step of a plan, what done means |
after, offset | nach, abstand | a plan: this step is due offset (2w, 14d, 1m) after the step named in after |
How rows are read: lists.
Environment variables
Section titled “Environment variables”They are listed under running Nota.