Artifact 695e3fad8c7be83d229b6fcd2c32b32eacdef18c0f64d22b6e9378808e065302:
- File
docs/api.md
— part of check-in
[c754084dc7]
at
2026-08-17 15:52:12
on branch trunk
— web: the files page was unusably slow; fix the query, memoise, cap the list
Three separate faults, worst first.
Branches() used a correlated subquery — one full scan of checkin per row. On tcl (42,074 check-ins, 1,855 branches) that took 434 SECONDS, which is what made the page look hung rather than slow. One grouped scan with SQLite's bare-column-with-max rule, plus an index on (branch, date): 0.042s.
'ls --long' costs ~4ms per file because it reads each blob for size and the binary flag, so tcl's 2,198-path tip took 8.5s. Fossil never pays this — browse.c builds a directory listing from its own indexed tables and shows no size at all — but quarry reads through the CLI by design, so the answer is to compute once: a check-in's file set is IMMUTABLE, so listings are memoised per version, the tip is warmed after each ingest, and the tree op resolves 'trunk' to its hash so the page asks for the key that was warmed.
Only a hash may be cached. Caching 'trunk' would serve a stale tree forever after the next commit — a correctness bug dressed as a performance fix — so the memo refuses anything that can move, with a test pinning it.
The branch selector rendered every branch: 1,855 <option> elements, 90% of a 239KB page, and unusable as a control. Now the 25 most recently active, plus the branch being viewed even when it is older.
tcl's repo home: 8.5s -> 0.38s, 239KB -> 29KB. sqlite: 5.0s -> 0.32s. (user: dmestas, size: 11908) [annotate] [blame] [check-ins using]
quarry API
Generated from the op registry by quarry docs — edit the ops, not this file; regenerate with make docs.
Every op also appears in the OpenAPI document (quarry spec). Query inputs ride the query string; the same names work as JSON.
attachment.get
GET /api/v1/r/{repo}/attachment/{hash} — query, anonymous
Fetch one attachment's content by its content-artifact hash.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
hash |
string | required,min=4,max=64 |
Output fields:
name(string)size(integer)content(string)
branch.list
GET /api/v1/r/{repo}/branch — query, anonymous
List branches with their tip check-in, most recently active first.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
Output fields:
branches(array of object {name: string, tip: string, date: string})count(integer)
checkin.diff
GET /api/v1/r/{repo}/checkin/{hash}/diff — query, anonymous
Diff one check-in against its primary parent.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
hash |
string | required,min=4,max=64 |
Output fields:
from(string)to(string)files(array of object {status: string, name: string})unified(string)note(string)
checkin.get
GET /api/v1/r/{repo}/checkin/{hash} — query, anonymous
Describe one check-in: metadata, parents, and its file set.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
hash |
string | required,min=4,max=64 |
Output fields:
hash(string)ci(string)branch(string)date(string)user(string)comment(string)parents(array of string)files(array of object {blob: string, name: string, size: integer, perm: string, binary: boolean})
ci.list
GET /api/v1/r/{repo}/ci — query, anonymous
List a repository's CI runs, newest first.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
limit |
integer | min=0,max=200,default=50 |
Output fields:
runs(array of object {runId: string, checkin: string, workflow: string, pipeline: string, status: string, started: string})count(integer)
file.get
GET /api/v1/r/{repo}/file/{hash}/{path...} — query, anonymous
Fetch one file's content at a check-in.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
hash |
string | required,min=4,max=64 |
path |
string | required,max=512 |
Output fields:
hash(string)path(string)size(integer)binary(boolean)content(string)html(string)
file.history
GET /api/v1/r/{repo}/history/{version}/{path...} — query, anonymous
List the check-ins that changed one file, newest first.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
version |
string | max=100 |
path |
string | required,max=1024 |
limit |
integer | min=0,max=200,default=50 |
Output fields:
path(string)version(string)changes(array of object {hash: string, date: string, user: string, comment: string})count(integer)
forum.get
GET /api/v1/r/{repo}/forum/{root} — query, anonymous
Fetch one forum thread: every post, rendered, in reading order.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
root |
string | required,min=4,max=64 |
Output fields:
root(string)title(string)posts(array of object {hash: string, parent: string, date: string, user: string, html: string})
forum.list
GET /api/v1/r/{repo}/forum — query, anonymous
List a repository's forum threads, most-recently-active first.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
Output fields:
threads(array of object {root: string, title: string, posts: integer, updated: string, user: string})count(integer)
forum.post
POST /api/v1/r/{repo}/forum — command, token
Open a new forum thread.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
title |
string | required,max=200 |
body |
string | required,max=1048576 |
mimetype |
string | max=64 |
Output fields:
hash(string)
forum.reply
POST /api/v1/r/{repo}/forum/{root} — command, token
Reply to a forum post within its thread.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
root |
string | required,min=4,max=64 |
body |
string | required,max=1048576 |
mimetype |
string | max=64 |
Output fields:
hash(string)
meta.docs
GET /api/v1/docs — query, anonymous
The API reference, generated from this registry and rendered.
Output fields:
markdown(string)html(string)
meta.version
GET /api/v1/version — query, anonymous
Report the quarry build version.
Output fields:
version(string)
repo.list
GET /api/v1/repos — query, anonymous
List the served repositories with their tip check-in.
Output fields:
repos(array of object {name: string, checkins: integer, tipDate: string, tipComment: string, indexing: boolean})count(integer)
search.query
GET /api/v1/r/{repo}/search — query, anonymous
Full-text search over a repository's check-ins, wiki, and tickets.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
q |
string | required,max=200 |
limit |
integer | min=0,max=200,default=50 |
Output fields:
results(array of object {kind: string, ref: string, label: string, snippet: string})count(integer)
technote.add
POST /api/v1/r/{repo}/technote — command, token
Record a technote; passing an existing event id records an edit.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
body |
string | required,max=1048576 |
mimetype |
string | max=64 |
comment |
string | max=200 |
event |
string | max=64 |
Output fields:
event(string)hash(string)
technote.get
GET /api/v1/r/{repo}/technote/{event} — query, anonymous
Fetch one technote, rendered, by event-id prefix.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
event |
string | required,max=64 |
Output fields:
event(string)date(string)user(string)comment(string)body(string)html(string)
technote.list
GET /api/v1/r/{repo}/technote — query, anonymous
List a repository's technotes at their latest edit, newest first.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
Output fields:
notes(array of object {hash: string, event: string, date: string, user: string, mimetype: string, comment: string, body: string})count(integer)
ticket.get
GET /api/v1/r/{repo}/ticket/{id} — query, anonymous
Fetch one ticket: folded state plus change history.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
id |
string | required,min=4,max=40 |
Output fields:
ticket(object {id: string, created: string, updated: string, fields: array of object {name: string, value: string}, description: string, descriptionMimetype: string, comments: array of object {hash: string, date: string, login: string, username: string, mimetype: string, body: string}, changes: array of object {hash: string, date: string, user: string, fields: array of object {name: string, value: string}}})descriptionHtml(string)comments(array of object {date: string, login: string, username: string, html: string})attachments(array of object {hash: string, name: string, src: string, date: string, user: string})
ticket.list
GET /api/v1/r/{repo}/ticket — query, anonymous
List a repository's tickets with their folded current state.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
limit |
integer | min=0,max=200,default=50 |
before |
string | max=96 |
Output fields:
tickets(array of object {id: string, title: string, status: string, updated: string})count(integer)next(string)
ticket.new
POST /api/v1/r/{repo}/ticket — command, token
Open a new ticket.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
title |
string | required,max=200 |
status |
string | max=40 |
comment |
string | max=65536 |
Output fields:
id(string)hash(string)
ticket.set
POST /api/v1/r/{repo}/ticket/{id} — command, token
Record a ticket change; empty fields are left untouched.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
id |
string | required,min=4,max=40 |
title |
string | max=200 |
status |
string | max=40 |
resolution |
string | max=40 |
comment |
string | max=65536 |
Output fields:
hash(string)
timeline.list
GET /api/v1/r/{repo}/timeline — query, anonymous
List a repository's events — check-ins, wiki edits, ticket changes — newest first, paged by before.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
limit |
integer | min=0,max=200,default=50 |
before |
string | max=96 |
branch |
string | max=64 |
y |
string | oneof=all\|ci\|w\|t\|e\|f |
Output fields:
entries(array of object {kind: string, hash: string, ref: string, date: string, user: string, comment: string, branch: string, isLeaf: boolean, isMerge: boolean, parents: array of string, ci: string})count(integer)next(string)
tree.list
GET /api/v1/r/{repo}/tree/{version}/{path...} — query, anonymous
List one directory of a check-in, with the directory's README rendered.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
version |
string | max=100 |
path |
string | max=1024 |
Output fields:
version(string)path(string)entries(array of object {name: string, path: string, dir: boolean, blob: string, files: integer, size: integer, exec: boolean, link: boolean, binary: boolean})readme(string)readmeIn(string)
wiki.get
GET /api/v1/r/{repo}/wiki/{name} — query, anonymous
Fetch one wiki page, rendered — latest, or the revision named by rev.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
name |
string | required,max=100 |
rev |
string | max=64 |
Output fields:
hash(string)title(string)date(string)user(string)mimetype(string)source(string)html(string)
wiki.history
GET /api/v1/r/{repo}/wiki/{name}/history — query, anonymous
List every recorded edit of one wiki page, newest first.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
name |
string | required,max=100 |
Output fields:
title(string)edits(array of object {hash: string, date: string, user: string})count(integer)
wiki.list
GET /api/v1/r/{repo}/wiki — query, anonymous
List a repository's wiki pages with their latest edit.
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
Output fields:
pages(array of object {title: string, date: string, user: string})count(integer)
wiki.save
POST /api/v1/r/{repo}/wiki/{name} — command, token
Record a wiki page edit (creates the page on first save).
Input:
| field | type | rules |
|---|---|---|
repo |
string | required,max=64 |
name |
string | required,max=100 |
body |
string | required,max=1048576 |
mimetype |
string | max=64 |
Output fields:
hash(string)