Using it — the doors, the CLI and the API

Two ways in

The CLI wraps the API and holds the credential, so most tools never see a token. The API is the same surface without the wrapper, and it is the front door for any AI that connects directly.

The route reference is the OpenAPI spec the API serves at /api/json, readable at /api. Both are relative to the API base, not the host — on prod the base is /api/lattris, so the spec is at https://lattris.com/api/lattris/api/json. It is the reference, not a promise of completeness: some routes are still missing their documentation. It is honest about credentials: it requires a bearer credential on every route site-wide and marks the open routes with an empty security list. Read it for every route's shape and its credential, and read this block for what the spec cannot carry: which door to use when, and why.

What shipped in code is the repo's record, not this tree's. The merged pull requests of foundations-io and the runs of its deploy workflow, named Continuous Deployment, say what reached prod and when. The tree keeps no deploy list.

The CLI

  • lattris login signs in through the browser.

  • lattris whoami prints who the session acts as, and quietly refreshes an expired token.

  • lattris use <actor> binds a directory to an identity, so different workspaces act as different people on one machine.

  • lattris capture memory saves a note from stdin. --ai-summary gives it its abstract in the same call, and --linked-from <id> or --links-to <id> wires one edge as it is created — the existing block pointing at the new one, or the new one pointing out.

  • lattris capture session saves a whole conversation from its transcript. lattris capture recording keeps an audio recording, its source, or its transcript — a vendor transcript is converted here, because the door meets one shape.

  • lattris link <from> <to> --verb --reason writes an edge, lattris unlink <from> <to> --verb removes it, and lattris update edge <from> --verb --to --reason rewrites the reason. --reason is required and the CLI never invents one.

  • lattris update recording transcript <id> <file> replaces the words; lattris update recording speakers <id> <key>=me|<contact-id>|clear names who spoke.

  • lattris set banned-words shows this account's list, and replaces the whole list when given words.

  • lattris close question <id> --close-as updated|declined|already-answered closes an ask.

  • lattris get memories lists. lattris get memory <id> reads one back with its links, and --depth <n> walks on from there — one call can pull most of a tree that way, which the reading rules forbid, so raise it only when you mean to.

  • lattris update memory <id> corrects one. The new words arrive on stdin, the way capture takes them, and the banned-word gate fires on them with --allow-banned-words as the override. Three flags ride with it:

    • --title retitles
    • --intent <name> re-declares what it is
    • --clear-intent takes it back to none

    The CLI reads the block first and sends the updatedAt it read, so a block that moved in between is refused rather than overwritten, and --overwrite skips that check.

  • lattris share memory <id> --with public grants. lattris unshare withdraws.

  • lattris setup moves an AI workspace onto Lattris as its memory.

  • Your own settings live on your person record. GET /person/me reads them back with your preferences; PATCH /person/me writes them, replacing a preference whole per key. Two keys exist: banned_words, the list the write doors check, and ask_requires_role_lines, true or false, which makes your questions door refuse an ask that lacks a For line or a Filed by line.

  • --as <email> acts as another local actor for one command. --env prod targets production instead of local. Sessions are stored per actor, per environment.

Reading

GET /memories/{id} returns a block. Add ?links=1 for its edges and their reasons, and &content=0 when you only need the shape. Every link's node and the anchor's own node carry href, the absolute read address of that block with links=1, in the public form on the public door and the authenticated form on this one, so a reader follows a link by opening its href and never builds an address. The public read door answers the block as a page when the caller's Accept prefers text/html or format=html rides on the address: every link is a real anchor carrying its verb and reason, and a footer anchor points at the JSON form. format=json forces JSON whatever the Accept says, and a JSON caller sees no change. The door speaks both. The website's public pages, the homepage and any public block address, carry the block's title, summary, words and one anchor per link in their HTML before any script runs. They are filled from the anonymous read, so a private block reads not-found for everyone, with a short shared cache keyed on the block's updatedAt, and the plain shell when the fill cannot happen.

GET /memories lists newest first and takes filters: q= searches titles and content, topic= narrows to one topic's members.

A public tree is read at /by/{handle}/memories without signing in, and a block can be addressed by its full id, its short handle, or its slug. An id obtained outside the tree can return 404, and a 404 deliberately does not tell you whether the thing does not exist or is simply not yours to see.

There is no history. A block has one version, the current one. updatedAt says when it last changed, and no route returns what it said before — there is no versions, revisions or audit door to find. One caveat, and it is real: a captured session is an ordinary block on this tree, and its transcript may describe what a block used to say. That is a side effect, not a history door — it exists only where someone saved a conversation that discussed the change, and it is a description of the edit, not the old text.

Writing

  • POST /memories/notes creates a note, and takes aiSummary in the same call. The create door refuses unknown fields rather than ignoring them.
  • PATCH /memories/{id} corrects a block, and re-declares intent: omit the field and it stays as it was, send null and it clears. It also takes expectedUpdatedAt, the updatedAt a content read returned. A read with content=0 carries no updatedAt, so the version field comes only from a content read. When the block has changed since that read, the door refuses with 409 and memory:stale-write, writes nothing, and says: "This block changed at , after the version you read (). Nothing was written. Re-apply your change to detail.current and retry with its updatedAt." Send no version and the write lands as before.
  • Both of those doors check the title and the content against a list of banned words. The list is yours to set, and a preference you never set is not the same as one you set to nothing: absent means the door was never asked to check, empty means you asked it to check against nothing. A refusal names every word it caught and the field that overrides it, allowBannedWords: true. The house voice says which words and why.
  • POST /memories/{id}/edges links two blocks you own. The body takes verb, toBlockId and reason. All three are required; omit one and the call returns 400.
  • PATCH /memories/{id}/edges changes an existing edge's reason. It takes verb, toBlockId and the new reason. The verb and the two ends are the edge's address, not fields you can edit — send a different verb and you get a 404, because you have named an edge that does not exist.
  • DELETE /memories/{id}/edges takes verb and toBlockId, no reason.
  • PUT /memories/{id}/topics/{topicId} adds a membership. Sending it twice does nothing the second time.
  • POST /memories/recordings keeps a recording. It stands on any one of three things: held audio, a source it lives at, or a transcript. The transcript arrives whole, speakers and turns together.
  • PUT /memories/{id}/speakers corrects who a voice belongs to, keyed by the speaker label the transcript already carries.
  • POST /spans creates a span, and a block joins one when it is created.

Sharing

Everything is private until granted. POST /memories/{id}/grants makes a block public; DELETE /memories/{id}/grants/public withdraws it.

What you grant is the block, not the account, so a tree can be half published. Absence of a grant is the privacy state, and the server enforces it: a stranger reading a private tree gets the same answer as a stranger reading a tree that does not exist.

The door for questions

When a published tree cannot answer something, POST /by/{handle}/questions leaves the question with its owner. Signing in is required — a question carries its asker. There is no live reply, by design. The answer is the tree changing before the asker comes back.

Who is reading

Three kinds of caller reach this surface:

  • The tree's owner — sees everything, private included.
  • A signed-in person — sees what was granted to them, and writes only to their own account.
  • Anybody without a credential — sees only public blocks, at /by/{handle} alone.

The server decides which you are from the credential. Nothing asks you to declare it.

Probe. Asked to show exactly what a block said before its last edit, what can a session that has read only this block answer, and why? It has to get there without hunting for a history route first.

Leads here