The served API

The routes on this page are the ones that keep what they are given. They sit on our server, reached through the site's proxy, with ?corpus=<text> on every call. Each is signed by the browser's key. Numbers here are positions in the reading, never words, unless the row says words.

Rooms: kept, append-only

route	request	response	keeps
POST /social/<room>/comment (signed)	user_did, text, anchor, context_digest (the SHA-256 of the words it was made on), parent_comment_id, user_name; in a writer's room a context_text is refused	the comment with its id and time	the remark, its position and digest, under the room; no delete exists
POST /social/<room>/share (signed, the writer)	writer_did, paragraphs (pid, text), code_sha256	the share	the paragraphs as shared, appended; a later share supersedes an earlier one
POST /social/<room>/join (signed, a member)	user_did, code	joined	the join, appended
POST /social/<room>/share/end (signed, the writer)	writer_did, reader_did or none for the whole share	the share's state	an end record; a removed reader stays removed; an ended share's words stay sealed
POST /social/<room>/share/readmit (signed, the writer)	writer_did, reader_did	who stays removed	a readmit record; the removal stays on the record; the reader joins again with the link
PUT /social/<room>/members (signed)	writer_did, members	the list	the list, beside the room; the first PUT fixes the writer

Members and grants

route	request	response	keeps
POST /members/grants	a grant and the Foundation's signature over it	ok, or 403	the grant, appended; the server holds no secret, only the Foundation's public key
POST /members/bind (signed)	the member ID, a former desk ID and its key	ok	the binding, appended

A signed write carries three headers: the public key, the time in milliseconds, and an Ed25519 signature over habitat-member-v1, the method, the room id, the time and the SHA-256 of the body. The server refuses a key that does not name the ID, a bad signature, a clock more than five minutes off, or a replay.

Gem-Space: kept, append-only

route	request	response	keeps
POST /gemspace/<room>/gift (signed)	the gem file as text	appended, and the new state	the whole gem, which carries no words; one gem per person per session; an earlier one is ended by a record naming its replacement
POST /gemspace/<room>/end, /session-end (signed)	the gift id; or nothing	the state	an end record; the session-end record keeps the signed request so it can be re-verified

Limits

Reads serialize behind one lock, so the server answers one reading at a time. The replay memory for signed writes is in process memory and does not survive a restart. What the room and Gem-Space routes keep is kept indefinitely; no retention script exists today.