Skip to content

Sending records yourself

Any program can be a source. It takes one HTTP call.

Terminal window
./nota token add my-source ingest

The token is shown once. Its name, my-source, is recorded as the source of every record it sends.

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.

Terminal window
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/v1/ingest -d '[
{"type":"thing","thing":"web-1","kind":"server","name":"Web 1","expect_s":180,
"price":{"amount":"7.00","currency":"EUR","per":"month"}},
{"type":"edge","thing":"web-1","rel":"part_of","target":"shop"},
{"type":"metric","thing":"web-1","metric":"disk_used_ratio","value":0.97},
{"type":"state","thing":"shop","check":"tls","status":"ok","summary":"certificate","due":"2026-12-05T00:00:00Z"},
{"type":"event","thing":"backup-db","event":"run","outcome":"fail","summary":"pg_dump exit 3","vars":{"exit_code":"3"}},
{"type":"cost","thing":"shop","amount":"12.40","currency":"EUR","from":"2026-11-01T00:00:00Z","to":"2026-12-01T00:00:00Z"}
]'

Every record has a type, a thing — an id you choose: letters, digits and . _ : @ - — and optionally a time ts. A thing exists from its first mention.

You want to sayRecord
“This exists, it is called so, it costs that.”thing, with kind, name, price
“I will report on it at least this often.”thing with expect_s — silence beyond it is critical
“This belongs to that.” / “This runs on that.”edge with rel part_of, runs_on or depends_on
“This check is ok / warning / critical.”state, with check, status, summary, optionally due
“This is owed, to me or by me.”state with amount, currency, side
“This ran, and it went well or badly.”event with outcome ok or fail
“This happened and cost that.”event with amount, or with a quantity that an event price turns into a cost
“Here is a number.”metric — compared against threshold rules
“In this period it cost / brought that.”cost, revenue

All fields are in the reference.

An event with an outcome is a run. A failure turns the check of the same name critical until a run succeeds:

{"type":"event","thing":"backup-db","event":"run","outcome":"ok","summary":"backup ran"}

A rule of the type expect notices when no successful run arrives in time — a backup that silently stops. The rules that ship expect a run of every thing of the kind backup at least every 26 hours.

Each step is an event. A tool call brings its own price; tokens carry a quantity that a price per event turns into a cost:

[
{"type":"event","thing":"assistant","event":"input-tokens","quantity":4200000},
{"type":"event","thing":"assistant","event":"output-tokens","quantity":610000},
{"type":"event","thing":"assistant","event":"web-search","amount":"0.35","currency":"USD","summary":"12 searches"},
{"type":"event","thing":"assistant","event":"ticket-resolved","quantity":57}
]

These are the records of the AI scenario. An event price on the revenue side turns the 57 solved tickets into what they brought.

A step that fails carries what it knew in vars, and a Brief template can name it: {{vars.model}}.

{"type":"event","thing":"web-1","event":"fix","summary":"rotated the logs","vars":{"check":"disk"}}

The next Brief for that check carries the sentence.

The views the dashboard draws from are an HTTP API as well, with a read or operate token: reference.