Repository navigation
A source's documents cannot be read back by the external_id they were pushed under #1276
Description
A client that pushes to an api or statements source names each document by its own external_id, but cannot read a document back by that name or list the names it has pushed. It has to remember Utopia's document ids, or search for its own text.
Our use: a backend keeps small records (notes keyed by name, one document per file of a repository) in a source, and needs "give me the current text of notes/deploy", its versions, and "which names under notes/ are live".
Proposal, as two small PRs:
- read one:
GET /kbs/{id}/sources/{sid}/documents/by-external-id?external_id=…returns the document's metadata, its current text and its version list (old versions through the existingGET /documents/{id}/content?version=N); a tombstoned id is 404 unlessinclude_missing, a purged one 410 - list:
GET /kbs/{id}/sources/{sid}/documents?prefix=&cursor=&limit=lists live names in byte order with keyset paging, behind aCOLLATE "C"index on(source_id, external_key)
Both take a session or a personal token (Viewer, kb_ids narrowing, as document content does), not the source key, so a leaked push key stays push-only (0052).
Related: #1268 / #1275 (a declared external_id stays the document's identity), #1262 (token reads), #1271 (search by external_id prefix).
Activity
gedaiu commentedon Oct 18, 2026
You mentioned on #1277 that this one comes first too. The shape I'd propose is the one in draft #1280:
GET /kbs/{kb}/sources/{source}/documents/by-external-id?external_id=…(a query parameter, since ids can contain/), Viewer level and open to a read token like document content, answering the document or 404. On the ADR side I'd add a dated revision note to 0052 instead of editing its decision. Does that work for you, or would you prefer a filter on the existing documents list?WaylandYang commentedon Oct 19, 2026
Thank you. Yes to the narrowed shape: one
GET …/sources/{source}/documents/by-external-id?external_id=…, Viewer, open to a read token, 404 when there's no such document, with a dated revision note on 0052. A list endpoint isn't needed now. #1268 has landed, so a declared id now keeps its document and this route means what it says.When you rework #1280, three things from the review: build the source key with one helper shared with the push handlers (it's currently built in three places); check the trash, tombstone and key on the row
read_retainedactually locks, not on the row read before the lock; and put the route in 0014's decision 7 with the other token reads.WaylandYang commentedon Oct 22, 2026
Done on dev in #1280:
GET /kbs/{id}/sources/{sid}/documents/by-external-id?external_id=…returns the document, its current text and its versions to a session or a read token, 404 otherwise. The list-by-prefix part was set aside as not needed now; please open a fresh issue if it becomes one.