How immut fits together
This page explains what immut stores and how the pieces relate. Read it before you build an agent that reports on someone's records. The API reference tells you how to call each endpoint. This tells you what the answers mean.
Agent summary
- immut proves one thing: this exact content existed no later than the moment immut received it.
- Everything else on a record is an assertion by whoever supplied it. Label it that way.
- A version is a separate document with a parent. Versions do not appear in
list_documents.- A staged file has no proof and appears in no other list. It is not protected.
- Permanence follows the network on each proof, not the plan.
- Raw twin of this page: /docs/concepts.md.
What does immut prove?
That a specific sequence of bytes existed no later than the moment immut received it.
That is the whole claim, and it is worth being strict about. immut anchors a fingerprint of the file to a public record. Anyone can later check that the file they hold matches that fingerprint, and that the anchor is older than the challenge. immut does not need to exist for that check to work.
What immut does not prove: who wrote the file, or whether it is true. Nor the date printed on it, nor when it was edited. Those are claims someone else is making. Your agent may repeat them. It must not present them as proven.
Which parts are evidence, and which are claims?
This is the distinction that decides whether a report survives a challenge.
| Field | What it is | Proven? |
|---|---|---|
createdAt | When immut received and anchored the file | Yes. This is the evidence |
txHash, network | The public record the anchor lives in | Yes. Anyone can check it |
fileHash | The fingerprint that was anchored | Yes |
documentDate | The date printed on the document | No. An agent read it |
parties | Who the document involves | No. An agent read it |
docType, docState | What kind of document, and its state | No. An agent judged it |
agentClassification | Why the agent chose to protect it | No. It is reasoning |
Report both kinds. Keep them visibly apart. A reader who cannot tell which is which has to distrust all of it.
How are the pieces arranged?
organisation
└── workspace the top container, and the unit a proof is paid from
└── folder a tree, and folders can nest
└── document one protected file
├── version a later revision of that file
└── proof the anchor for that exact content
└── certificate a PDF of the proof, for a person to hand over
A document belongs to exactly one organisation and one workspace. A folder is optional. Nothing is shared between organisations. An id from another organisation returns 404, never 403, so you cannot use the API to test whether an id exists elsewhere.
What is a version, exactly?
A separate document that points at the original as its parent.
That has one consequence that catches people out. list_documents returns only root documents. Versions are filtered out. So the count you get back is "how many things are protected", not "how many files were uploaded". To see a chain, call list_versions on the document.
Each version gets its own proof and its own timestamp. Be precise about what that proves: it shows that version's content existed by the time immut received it. It does not show when the edit was made, so never date the change itself.
A chain of versions is still worth more in diligence than a single file. It shows the shape of the work over time, which is usually the question being asked.
What is a staged file?
A file an agent uploaded but did not protect, because it could not decide.
A staged file has no proof and no public record. It is excluded from list_documents, from every count, and from every export. list_review_queue is the only place it appears. Do not include one in a protected total, whatever else the response says.
A person then approves or rejects it. Approving creates the proof at that moment, so the timestamp is today, not the day the agent found the file. Rejecting deletes the bytes and the row for good. Staged files are removed automatically after 90 days.
What is a run, and why does it matter?
One sweep. An agent reports it with report_run when the sweep ends, including a sweep that protected nothing.
Runs are how immut notices that an agent has stopped. A sweep you do not report looks exactly like an agent that broke.
A run can carry the decisions the agent made, including files it chose to leave alone and why. That list is consent-gated, so an empty list does not mean nothing was excluded. It may mean the customer never agreed to share reasoning. The export says which of the two it is; do not guess.
Tie your uploads to the run. Send the same runId on every file you protect and on report_run. Without it the run shows no documents, and the diligence pack carries no reasoning for those files.
What decides whether a proof is permanent?
The network on that individual proof, and nothing else.
Read the network field on every result. Only a mainnet proof is permanent and court-ready. A testnet proof is an impermanent demonstration, and an agent must present it as one. Do not infer permanence from the plan, the price, or from another proof on the same account.
How does a file get from a drive into evidence?
Two routes, and they meet in the same place.
- The agent skill runs on the customer's own machine, reads their files, decides what matters, and uploads what it chose. It records its reasoning as it goes.
- The connector or the API takes bytes you already have. Nothing reads a disk.
Either way the file is hashed, anchored, and becomes a document with a proof. A file uploaded by hand through the web app has no reasoning attached. An agent can read it back and describe it afterwards. That loop is on the investor report page.
Where do I go next?
- Connect an agent, then the MCP connector or the API reference.
- Agent playbook for how an agent should behave.
- Build an investor report for the read, describe and report loop.
- Verify a document to check a proof with no account and no key.