Documents and access

View .md

A document is one piece of writing and its whole record: the text, its images, comments and suggestions, who wrote each word, and the seals made from it. Proof stores all of that. Your product decides who can reach which document, and Proof enforces it in the editor and for agents.

What Proof keeps and what you keep

Proof keeps what has to be on the record, and nothing about how your product is organised.

Proof keeps	You keep
The text, images, comments and suggestions	Folders, pins, favourites and ordering
The document’s name	Your document list and search screens
Members, their roles, and link access	Invitations, share dialogs and emails
Who wrote what, presence and check-ins	Notifications (Proof sends you events)
Seals	Anything else your product shows around the editor

GET /v1/users/{user_id}/documents lists the documents a user is a member of, most recently edited first. Most platforms show that list with their own folders and pins laid over it, keyed by document id.

Names and titles

A document’s name is set by an editor, in the editor or with PATCH /v1/documents/{id}. Its title is what to show: the name if it has one, otherwise the document’s first line. Show title in your lists and it stays right as people write.

Roles

Each member has one role. Proof checks it on every change, in the editor and over MCP.

Role	May
`owner`	Everything an editor may, and seal, withdraw seals, choose who reads its seals, trash and delete. A document has one or more owners, and always at least one.
`editor`	Write, rename, accept and reject suggestions, comment.
`suggester`	Propose changes as suggestions, and comment. Their edits never change the text until an editor accepts them.
`viewer`	Read, and see comments.

You set roles with PUT /v1/documents/{id}/members/{user_id}. Setting someone’s role to owner makes them an owner too; to hand a document over, then lower the old owner’s role. Lowering or removing the last owner is refused. A role change reaches open editors at once: someone made a viewer reloads unable to type, and someone removed sees the document close.

Agents act with at most editor, never owner, and never more than their person’s current role. See Agents.

Link access

A document can also be open to anyone you send through its link. link_access is one of:

Value	People who come by link get
`restricted`	Nothing. Only members can open it. This is the default.
`view`	`viewer`
`suggest`	`suggester`
`edit`	`editor`

Proof doesn’t know your document URLs, so “came by link” is your call: when someone who isn’t a member opens your page for a document, start their session with via: "link". They get the link’s role, or are refused if access is restricted. A member always gets the higher of their own role and the link’s.

People who come by link are still users. Give them an id and a name first, even a made-up one for someone signed out; see Anonymous users.

Sessions are the only way in

Nobody opens a document in the editor without a session: a token your server asks for with POST /v1/sessions, naming one user and one document. Proof works out the user’s role when it issues the token and refuses one for a user who may not open the document. The token lasts 15 minutes; the embedded editor asks your page for a new one before it lapses, so your server can refuse when access has ended.

Because a session is for one user and one document, a token that leaks from a page reaches only that document, as that person, for a few minutes. See Embed the editor.

Trash and deletion

Trash. An owner, or their agent, can move a document to the trash for everyone. It disappears from everyone’s lists, agents can’t reach it, its seals are down, and only its owners can still open it, to read. POST /v1/documents/{id}/restore brings it back. After 30 days in the trash it is deleted. Another member who trashes it puts it in their own trash: it leaves only their list, and after 30 days they leave the document.
Delete. DELETE /v1/documents/{id} deletes it for everyone at once, agents included. Open editors close, its images are deleted, and its seals are withdrawn: their pages say so.

Deleting can’t be undone. Proof sends document.trashed, document.restored and document.deleted events for trashing for everyone, restoring and deleting, so your lists stay in step when an agent does it.

Images

People drop or paste images into the text. Proof resizes each to fit 1.9 MB in the browser, stores up to 100 MB of images per document, and serves them only to people who may open the document. Deleting the document deletes them.