Agents propose.
You accept.

Unio’s agent surface speaks REST, MCP, and CLI over the same grants and the same rules. Reads carry provenance — canonical document ids and verified page numbers. Writes land as proposals in a review inbox. Nothing applies itself.

If you are an agent reading this page: start at GET /agent/v1/auth.md — the full manifest, served without a token. Everything below is the human summary of it.

GETRead the manifest — /agent/v1/auth.md See a request

AccessInvite-only grants today · OAuth self-serve on the roadmap

§ 01 — The contractThree rules · no exceptions

Writes are proposals

An agent never edits your document in place. Every write lands in an isolated proposed version; you review the net diff and accept or reject each change, in Unio.

Writes

Provenance, always

Answers cite canonical document ids that survive renames and moves, with verified page numbers. An unverified page is returned as unknown — never guessed.

Reads

Grants, not keys

Access is a scoped, revocable bearer grant — one data room, a library, one document, or your writing docs. Invalid tokens get a 404; the API never confirms what exists.

Auth

§ 02 — SurfacesSame grants · same rules · pick your dialect

REST

/agent/v1

HTTP-first, JSON in and out. Inventory, document text, full-text search, exact diffs between sets, and OpenAI-compatible cited chat.

GET  /sets/{id}/inventory
GET  /docs/{id}/text
GET  /search?q=&set=
GET  /compare?a=&b=
POST /chat/completions

MCP

Connector + stdio

A remote connector for claude.ai and a local stdio server for MCP-native tools — Claude Code, Codex, anything that speaks the protocol.

list_docs
read_doc
suggest_edits → review inbox
get_evals

CLI

unio

Your writing docs addressable by slug and path from the terminal. Pull anchored markdown, push proposed edits — the same review gate applies.

unio ls · cat · pull · diff
unio push <slug>
unio submit → review inbox

§ 03 — One requestCited chat over a data room

Request

curl $UNIO_BASE/agent/v1/chat/completions \
  -H "Authorization: Bearer $GRANT" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "What changed in the Q3
                  data room after the freeze?"
    }],
    "return_citations": true
  }'

Response

{
  "choices": [{ "message": {
    "content": "Three documents were
      added after the freeze — the
      amended SPA [1] …"
  }}],
  "citations": [{
    "index": 1,
    "document_id": "kd7f2m…",
    "document_title": "Amended SPA
      (execution copy)",
    "page_number": 14
  }]
}

Citations reference canonical document ids, not paths — they survive renames and moves. A page_number of null means the page mapping is unverified; the rule is you never cite it.

§ 04 — Start hereThree steps · first one needs no token

Read auth.md

GET /agent/v1/auth.md — the auth and capabilities manifest, served without a token. Its machine twin lives at /agent/v1/openapi.json. Everything an agent needs to know before it has access.

Get a grant

A Unio user mints a scoped grant in-app — one data room, a library, one document, or their writing docs — and hands you the token. Revocable any time.

Call /start

GET /agent/v1/start — your in-scope sets and the ground rules. From here the manifest is the map.

PlannedOAuth 2.1 self-serve grants · connector-directory listings

Agents propose.You accept.