IRF 1.0 · The Irris Record Format

One envelope for any data

A sensor reading, a PLC event, a Postgres row, a PDF manual, a photo, an SOP. Each becomes a record Irris can find, cite and reason with.

Read the format Get started

The envelope

Two fields matter. The rest is up to you.

A record needs a type and at least one of text, data or title. Your fields go in data exactly as they are. Nothing is renamed or dropped.

application/json

{
  "irf": "1.0",
  "type": "reading",
  "source": "line-3/plc",
  "id": "press-7-temp-2026-11-02T08:15:00Z",
  "time": "2026-11-02T08:15:00Z",
  "subject": "asset:press-7",
  "title": "Press 7 platen temperature",
  "text": "Platen at 182 C during cycle 4410",
  "data": { "value": 182.4, "unit": "C", "cycle": 4410 },
  "units": { "value": "C" },
  "tags": ["thermal", "line-3"],
  "links": [{ "rel": "part_of", "to": "asset:line-3" }]
}

typeREQUIRED: What the record is. Any lowercase word works.
source: Where it came from, as a path: erp/orders, line-3/plc.
id: Your system's stable id. The same source and id again updates the record instead of duplicating it.
time: When it happened, in ISO 8601 or Unix seconds. Defaults to when Irris received it.
subject: What it's about, as kind:name. Records that share a subject are linked.
title, text: A short name, and human-readable content.
data: Any JSON. Your fields, as they are.
units, tags, links: Units for fields in data, free labels, and relations to other subjects.

Types

Some types get special handling

Any other type, like work_order, quality_check or shipment, is stored, indexed and searchable as it is.

type	What Irris does with it
document	Splits the text into passages, so answers cite the exact part and page.
reading	A measurement of the subject. Charted, and checked against limits.
event	An alarm, fault, stop or state change. Shown on the timeline.
procedure	An SOP. Its steps, checks and limits become a guided procedure on the camera.
asset	A machine, line, tool or instrument that other records point at.
lesson	A correction or rule your team taught Irris. Always considered when it answers.
row	A table row from a connected database or a CSV. The columns go in `data`.

Getting data in

Send IRF. Or send what you have.

You don't have to convert anything first. Anything that isn't IRF is wrapped in IRF for you.

Channel	What you send
POST /api/v1/ingest	One record, a list of records, or newline-delimited records for streams and big batches.
Any JSON	Any object or array, with `?type=` and `?source=`. Each object becomes a record.
Files	PDF, Word, Excel, CSV, JSON, Markdown, text and images. Documents are split into passages; spreadsheet rows become rows.
Postgres	A read-only connection string. Chosen tables sync, and the assistant can query live.
Webhook	Any JSON from any system, to a URL that carries its own secret.
MCP	Records from an AI agent, through the `ingest` tool.

Normalisation

What happens when it arrives

Anything that isn't IRF is wrapped: its type is the type you passed, or row, and the value goes in data.
Time becomes UTC, the type becomes lowercase, and unknown top-level fields move into data.
The record gets a searchable body from its title, text, subject, tags and every field in data.
A record with an existing source and id replaces the old one.

The original payload is always kept, unchanged.

Send your first record Developer docs